Parable PHP Framework 1.0.0

Parable PHP Framework Changelog

1.0.0

This release brings a major clean-up, documentation, useful new functionality and far more consistency.

If you're new to Parable, welcome! None of this is relevant for you, install and enjoy!

If you're upgrading from 0.12.x, this will be quite a whopper of a changelog for you to dig through, but it will definitely be worth it. Most changes are easily made (a test upgrade of an older 0.12.3 app I was working on took about 20 minutes) and it's much more complete than any previous versions.

Changes

• All method doc blocks now have explanatory text, even if it's superfluous, for documentation purposes.
• \Parable\Console\App now supports adding multiple commands in one go, using addCommands([...]).
• \Parable\Console\Command\Help now can generate a string for the usage of a command. Try it yourself: vendor/bin/parable help init-structure. Usage is also added to any exception caught by \Parable\Console\App's exception handler.
• \Parable\Console\Input received the following updates:
  • \Parable\Console\Input::getKeyPress() has been added. It will wait for a single key press and return its value immediately. Special characters like arrow keys, escape, enter, etc, will be returned as a string value accordingly.
  • \Parable\Console\Input::enableShowInput() and its buddy disable are now available for you to use. If disabled, hides the user's input as they enter it. Input will call the enable on destruct to prevent its effects lingering after exiting the script.
  • \Parable\Console\Input::enableRequireReturn() and its buddy disable are now available for you to use as well. If disabled, no longer requires an enter before returning input.
• \Parable\Console\Output received the following updates:
  • \Parable\Console\Output::writeBlockWithTags() was added, making it possible to write a block with multiple tags.
  • \Parable\Console\Output::getTerminalWidth() will return the columns available in the current terminal window. getTerminalHeight() will return the lines available.
  • \parable\Console\Output::isInteractiveShell() will return whether the script is running in an interactive terminal session or not.
• \Parable\Console\Parameter has been rewritten, and options and arguments are no longer just arrays of data, but actual classes. This allows much more fine-grained control over whether, for example, an option has been provided but there's no value to go with it.
• \Parable\Framework\App received the following updates:
  • It now has a HOOK_LOAD_ROUTES_NO_ROUTES_FOUND constant and triggers it when, you guessed it, no routes are found.
  • Quickroutes! It now has get(), post(), put(), patch(), delete(), options(), any() and multiple() methods, so there's an easy way of defining callback routes without having to set up the entire structure. any() accepts literally any method, or you can pass an array of the methods to multiple() as its first parameter.
  • Quickroutes also accept ["controller", "action"] style callbacks and will set them as discrete controller and action values on a route if the action is not a static function, to keep load down.
  • It also has setErrorReportingEnabled($bool) and isErrorReportingEnabled(). By default it's set to off. You can add parable.debug to the Config and set it to true to enable it.
  • It can now set the default timezone if you add a parable.timezone value to the config.
• \Parable\Framework\Dispatcher received the following updates:
  • It can now return the route it dispatched by calling getDispatchedRoute().
  • It now triggers two more events: HOOK_DISPATCH_TEMPLATE_BEFORE and HOOK_DISPATCH_TEMPLATE_AFTER. Use this to do something between a controller/callable being called and the template being loaded.
• \Parable\Framework\Mailer now supports setting a different mail sender. Default is, as it was, php's own mail().
• \Parable\Framework\Mailer now can act on three config values:
  • parable.mail.sender, which should be the class name of the SenderInterface implementation you want to use.
  • parable.mail.from.email, the email for the for address.
  • parable.mail.from.name, the name for the for address.
• \Parable\Framework\View now accepts more classes to be registered for use within Views. Call $view->registerClass($property, $className) and you can do $this->property_name->stuff() in your views.
• \Parable\GetSet\Base now also has setResource, for when you want to switch, or set it using a method rather than overwriting a property.
• \Parable\GetSet\Base::get() now accepts a second parameter $default which is the value to return when the requested $key is not found. Added by @dmvdbrugge in PR #30. Thanks!
• \Parable\Http\Request now has isOptions() to check for OPTIONS method requests.
• \Parable\Http\Request now has constants for all methods and all accepted methods are in Request::VALID_METHODS.
• \Parable\Http\Response now has setHeaders() so you can add a bunch of headers in one call, removeHeader($key) so you can remove a header, and clearHeaders() to, y'know, actually, I think you got this.
• \Parable\Http\Response::clearContent() was added, in case you want to just want to call appendContent() multiple times rather than one setContent() and then those appends.
• \Parable\Log\Writer\NullLogger was added, for when you want to log nowhere at all.
• \Parable\Mail\Mailer now obviously also supports setting a Mail Sender. Default is, well, none. That's all up to you to configure. (Hey, psst, Framework\Mailer already tries to do that for you!)
• \Parable\ORM\Model::create() has been added, making it much easier to instantiate a model. $user = \Model\User::create() is now possible.
• \Parable\ORM\Repository::createForModel() has been added, and will return a Repository instance for an already instantiated model.
• \Parable\ORM\Repository::getByCondition() has lost its 4th parameter $andOr, as it would always be a single condition and neither AND nor OR would ever come into play.
• \Parable\ORM\Repository::reset() has been added, and will reset Order by, Limit & Offset, only count and return one/all to their default values.
• \Parable\ORM\Query no longer supports setting the table key. This hadn't been necessary for a while, but the last remaining use of it has been removed. This shouldn't impact anyone much.
• \Parable\Routing\Route received the following updates:
  • In setUrl(), it now prepends a '/' if it isn't provided. Now you can add a url without the prepended slash if you find that cleaner.
  • It now makes sure all methods set on it are uppercase, for more consistent matching.
  • It now receives its own name and can be retrieved by calling getName() on it.
  • It now has setValues(), in case you want to overwrite all values. These will be passed to the controller or callable, in order. This makes it possible to intercept a dispatch and inject, for example, the request or response objects in addition to the parameter values from the url.
  • It now has createFromDataArray(), which can be used to create a Route object from the same type of data set in the Routing file in the structure.
• \Parable\Routing\Router now has a getRoutes() method that returns all set routes. In case you, err, need that.
• dynamicReturnTypeMeta.json has been added, removing the need for /** @var \Class $var */ references in the code. This works with the dynamic return type plugin in PhpStorm. Removed the few existing references that were there.
• It's now possible to set a new config value - parable.database.soft-quotes - to either true (default) or false. If true, Parable will fake quotes for values if there's no database instance available. If set to false, it'll refuse to quote instead.

Backwards-incompatible Changes

• Bootstrap.php has been removed. \Parable\Framework\App handles its own setup now. This makes it easier to implement App without much hassle.
• SessionMessage has been moved from the GetSet component into Framework, as it isn't a GetSet instance itself but merely uses the Session instance.
• \Parable\Console no longer accepts options in the format --option value, but only in the following: --option=value. This is because if you had an option which didn't require a value, and was followed by an argument, the argument would be seen as the option's value instead.
• \Parable\Console\App::setDefaultCommand() now takes a command instance rather than the name, as the name would suggest. To set the default command by name, use setDefaultCommandByName() instead.
• \Parable\Console\App::setOnlyUseDefaultCommand() was added, and the boolean paramater was removed from the setDefaultCommand/ByName() function calls. Checked by calling shouldOnlyUseDefaultCommand().
• \Parable\Console\Command::addOption() and addArgument() no longer take booleans for required or valueRequired but constants. See \Parable\Console\Parameter for the values. This adds the OPTION_VALUE_PROHIBITED possibility. Options can no longer be made required.
• \Parable\Console\Parameter has received several constants: PARAMETER_OPTIONAL, PARAMETER_REQUIRED, OPTION_VALUE_OPTIONAL and OPTION_VALUE_REQUIRED. This replaces the boolean functionality Parable had before. This makes it more readable.
• \Parable\Console\Parameter::setOptions() was renamed to setCommandOptions(), because the distinction is important.
• \Parable\Console\Output::writeError/writeInfo/writeSuccess() are now suffixed with Block, so writeInfoBlock(), etc.
• \Parable\DI\Container::cleanName() has been made protected. This shouldn't impact you, as you shouldn't've been using it in the first place.
• \Parable\Framework\Dispatcher no longer passes the Route to actions or callables as the first parameter. All parameters passed will be from the url params, in the same order as defined.
• \Parable\GetSet\InputStream::extractAndSetData() has been made protected. See above for why you should totally be fine.
• The interface \Parable\Log\Writer has been renamed and moved to \Parable\Log\Writer\WriterInterface for clarity and consistency.
• \Parable\Log\Writer\Terminal has been renamed to \Parable\Log\Writer\Console, because I don't know what was wrong with me when I chose 'terminal'.
• \Parable\ORM\Model::guessValueType() has been removed. Everything's a string now. Parable shouldn't change types for you. Honestly, when I added a method that started with guess, I should've doubted whether it was the right choice in the first place. Oh well.
• \Parable\ORM\Repository::onlyCount() has been renamed to setOnlyCount(bool), as the previous name suggested that calling it would enable only count mode, other than it being a toggle.
• \Parable\Routing\Route has lost the ability to use typed params. Too much code for too little gain. If you need typed parameters, I suggest you figure something out for yourself.
• \Parable\Routing\Route no longer supports template for the template path, but the more correctly named templatePath instead. Because of this, it now checks more strictly whether valid properties are set through the Routing array. setDataFromArray() attempts to call setters named like the properties. Any that are not available with a setter will throw an Exception. All properties are now also protected.
• \Parable\Routing\Router now also supports adding a completely set-up Route object directly (or in an array), without having to pass them as arrays, through addRoute() and addRoutes(). These methods already existed, but those are now renamed to addRouteFromArray() and addRoutesFromArray().
• The default structure's \Routing\App is now expected to extend the abstract base class \Parable\Framework\Routing\AbstractRouting and the old Interfaces\Routing interface has been removed. This removes passing routes as arrays!. See the new implementation, using the method calls on \Parable\Framework\App in the structure's app/Routing/App.php_struct.
• Two config keys were renamed: parable.session.autoEnable has become parable.session.auto-enable and parable.app.homeDir has become parable.app.homedir. The option for init-structure has also become --homedir.

Bugfixes

• \Parable\Console\Output had a bug where moving the cursors would mess with the functionality of clearLine(). Line length is no longer kept track of, but whether or not the line is clearable is a boolean value. Moving the cursor up/down or placing it disables line clearing, writing anything enables it again. When you clear the line, the line gets cleared using the terminal width.
• \Parable\Console\Parameter had a bug where providing an argument after an option with an = sign in it (so script.php command option=value arg) would see the argument as the option value and overwrite the actual value. Fixed by @dmvdbrugge in PR #31. Thanks!
• \Parable\Console\Parameter had a bug, where false-equivalent values passed to an option would be seen as the option being provided without a value, making the returned value true. Fixed by @dmvdbrugge in PR #37. Thanks!
• \Parable\Http\Response had a bug in appendContent() and prependResponse() where when working with arrays, empty values ended up as an empty array key, messing with json output.
• \Parable\Filesystem\Path::getDir() had a bug where if the filename you were trying to get a proper base-dirred path for already existed in the directory the code was run from, it would think it didn't need to and return just the provided path again.
• \Parable\Framework\Config had a bug where a class was referenced that doesn't exist until you've run parable init-structure. This has been replaced with a string value instead. Found by @dmvdbrugge. Thanks!
• \Parable\Routing\Router now sanitizes the Url before trying to match it, stripping html and special characters.