yamf php
1.0.0
YAMF (Yet Another MVC Framework) is a small PHP MVC framework designed to let you start using the MVC paradigm quickly without a lot of setup work. All you need is a web server that accepts .htaccess files and you're pretty much good to go!
Minimum requirements: PHP 7.0+.
Use this template button on the main project repo page.config.php if necessary. Adjust any parameters that you would like in there or add new parameters to $app, such as session logic. By default, you don't need to adjust anything to get your site up and running.config-private.sample.php to config-private.php and adjust it to your needs. For instance, you can setup $app->db to be a PDO instance for your local database. Note that config-private.php will be loaded before anything in config.php takes place.use Yamf/XYZ statements to work, you'll need to use Composer. Using Composer is pretty easy: just go to the download page and run the script at the top. (Note: if you're on Windows, you'll want to follow instructions here on the intro page.)composer install (if you've got a composer.phar file in your directory, run php composer.phar install). It will sit and think for a minute.They're not here, and they're not here on purpose! YAMF was purposefully written to not use any external dependencies other than Composer's autoloader to lower the barrier of entry to using the MVC paradigm in PHP. If you want any of those things, just pull them in with your favorite dependency manager (like Composer). Since Composer is already necessary to run this project for PSR-4 autoloading, we recommend using Composer. vendor/autoload.php is already included for you in init.php.
For a note regarding view templating, see the section on subclassing.
If you read the following documentation on YAMF, you'll likely be much better off than just hopping in and trying to read the code yourself. :) It will only take a few minutes, and it's worth it!
In order to facilitate easy passing of config parameters, such as database settings, etc., YAMF passes an $app variable of class YamfAppConfig to each Controller function. You can set up this variable to store your database PDO object, change your view extension or folder location, and many other settings. If you want to add your own values to $app, you can create a class that derives from YamfAppConfig and change the appConfigClass setting in config.php to point to your custom class. Note that your custom class must derive from YamfAppConfig! See config.php to see all of the settings and values that are passed by YAMF through $app. Notably, you can:
viewsFolderName)viewExtension)defaultHeaderName/defaultFooterName)config-private.php)$app is automatically available in your views for you.
The first thing you'll probably want to do is add a new route. To do that, follow these steps:
app/Controllers folder of the project. Subfolders are OK. The controller doesn't actually have to have Controller in the name, but make sure the class name matches the file name.public function that takes two parameters: $app and $request (in that order).routes.php and make sure you understand the documentation and examples of how routes work.routes array.
POST if necessary.Parent-Folder/Controller-Name format.yamf/Responses/Response, which can be anything from a View to a JSON response to, well, whatever you want, really. See the next section for more info here.yamf/Responses/View. Create a PHP file (view) in the views folder -- again, subfolders are OK -- and, in your controller method, return new View('name/of/view');.In short:
app/Controllers folderroutes.phpviews folder if necessaryreturn new View('name/of/view');All controller methods that are called as a result of a route should return a yamf/Responses/Response or a subclass of said class. Here are some descriptions on how to use each one. Most can be used in one line with just the constructor.
Response -- the base class for a response from a route.
new Response($statusCode = 200)yamf/Responses/Response items subclass from this parent class, they can all return a custom HTTP status code, if you want!ErrorMessage -- simple wrapper around View to send back a 400 status code and the error.php view.
new ErrorMessage($msg = '', $name = 'error', $title = '', $headerName = '', $footerName = ''). $name is the name of the view.$error. You can't change this without subclassing.views/header.php and views/footer.php.JsonResponse -- example on how you can send back a JSON response from your controller
new JsonResponse($data, $jsonEncodeOptions = 0)$data via echo json_encode($this->data, $this->jsonEncodeOptions);NotFound -- used for returning a 404 not found message back to the client.
new NotFound($name = '404', $data = [], $title = '', $headerName = '', $footerName = ''). $name is the name of the view.views/header.php and views/footer.php.Response.Redirect -- allows for a 302 redirect to some other page or route
new Redirect($redirectPath, $isInternalRedirect = true)$isInternalRedirect is used to redirect to a route within the current website/routes.php data. If you want to redirect to an internal route, use Redirect like this: new Redirect('/route/name); (note the starting /). If not, use Redirect like this: new Redirect('https://example.com', false);.View -- used for returning some PHP-based HTML view.
new View($name, $data = [], $title = '', $headerName = '', $footerName = ''). $name is the name of the view.compact function. See the sample's BlogController.views/header.php and views/footer.php.If you have ideas for more Response types that should be included in YAMF, please open a feature request (via the Issues tab) or open a Pull Request!
Two main variables are sent into your controller methods from the route: $app and $request. Note that all View output will have the $app and $request variables available to use. You do not need to send them as a $data parameter.
AppConfig $app$app is mainly configuration variables that you've set up in config.php. Check that file out for a quick glance at what's available. Some of the more important items are:
$app->db for a database connectionnull to avoid using them at all.In addition to those, there are two variables available that are set up in init.php:
$app->isLocalHost -- whether or not the application is running on local host (127.0.0.1 or ::1)$app->basePath -- the base directory for your current web application. This can be used to allow for nested web applications on your web server. I strongly recommend making use of this variable in your views when doing local website links so that if you move files around or later move things into a subfolder everything doesn't break. To link to another page on your site, just use the $app->yurl(string) (YAMF URL) function like this: <?= $app->yurl('/path/to/page') ?>.$request$request is going to have all your data about your route and the different parameters that have come in with your request. It's of type yamf/Request. It has these public members available:
$request->route -- raw route string for this request$request->controller -- string name of controller$request->function -- string name of controller function to call$request->routeParams -- any params in the route such as {id}. Format: ['id' => value]$request->get -- any GET params found in the URL -- same format as $_GET (no extra processing performed)$request->post -- any POST params -- same format as $_POST (no extra processing performed)$request->anchor -- If used, the # portion of the url (without the #). Router is smart enough to not match on URLs like /blah/#/foo.The easiest way for you to extend this framework is to derive from Response (or some other Response child class) and/or create a parent class for some of your controllers. For example, by deriving from View, you could change the view output to use the Twig templating engine instead of just simple PHP output. By creating a parent class for your controllers, you could add things like validation or other extra processing of data that has to happen for all of your API routes, such as verifying a username/password or token. The options are endless and the potential great!
There's an example of using Twig instead of raw PHP on the Twig branch!
One nifty feature that YAMF supports is static web pages that don't require a route or a controller. If you want /about to just be a simple page, throw an about.php page in the views/static/ folder and -- bam! -- /about works on your website. What about subfolders like /blog/post-name? That works too! Add a views/static/blog/post-name.php file and it Just Works (tm)! You can use this to still have pretty URLs on your website without bothering with adding routes and controllers.
You can configure the static views location in config.php.
Note that the router attempts to match a router.php route before checking for static pages.
A feature that the router supports that is not immediately enabled is URL shortening -- e.g. https://example.com/short-url. It requires a database connection, but if you add the database connection and have the appropriate database table (the schema is in config.sample.php), URL shortening can be used if you want. You're not required to enable this feature.
I've included some default session logic commented out in config.sample.php. Feel free to use it, modify it, or throw it out. If you have suggestions on how to improve this functionality, please open a pull request or an issue to generate further discussion.
Glad you asked! There are always things that can be done on an open-source project: fix bugs, new features, and more! Check out the issues tab of this repository and take a look at what bugs have been reported and which features have been requested. There's some more info on contributing in the Contributing document.
MIT License. Please make sure to include the license for this framework (along with a GitHub link if you're feeling generous!) when using it on your site. Thank you! :)
Special thanks to Bootswatch for the Bootstrap Paper theme used in the sample.
