Download for free and check out our documentation to get started. Download For Free

PyroCMS 3.1

Releases

PyroCMS 3.1 has been released! This is a pretty significant release for a "minor update" and brings in some very cool features and improvements with the primary addition of Laravel 5.3.

TLDR

  • Upgraded Laravel to 5.3.
  • Added publish commands for addon / streams resources.
  • Search module has been removed.
  • Streams Platform now provides search utilities based on Laravel Scout.
  • Changed reference to core overrides to streams to avoid confusion with Laravel resources.

Please update existing composer.json files for 3.0 installations to match https://github.com/pyrocms/pyrocms/blob/3.0/composer.json

Laravel 5.3

This is the main component that has been updated. The update to Laravel was the hardest aspect but at the same time the reason I decided to update in the first place!

The mailable and notifications API have been a roadblock in PyroCMS core module development. I have been hesitant to write my own and this just goes to show that good things come to those who wait! Scout support among other things made this upgrade a no-brainer.

Publish Command

Overriding config, views, and even translations in PyroCMS is such a powerful feature but a little hard to get the hang of at first. Now you can simply run a command and publish everything you need and start overriding config, views, and translations right away.

php artisan addon:publish // Publish all addons to the resources/{ref}/addons folder

php artisan streams:publish // Publish streams configuration to resources/streams

php artisan addon:publish anomaly.module.posts // Publish posts module only

php artisan addon:publish anomaly.module.posts --app=my_ref // Publish for an app other than the default one.

php artisan streams:publish --app=my_ref // Publish streams config for an app other than your default one.

It is important to note that you can publish and then delete unneeded overrides. Configuration / translations / views cascade backward version shipped with the addon.

For example you could publish resources for an addon and then remove all but one config file. And in that one file remove all but a couple config keys.. The published config will merge backwards through any global configuration overrides and then into the addon itself. This helps keep clutter out of your resources folder.

Search Module

The search module has been removed. Search is now provided by the streams platform and streams can now define a searchable attribute when migrating.

Previously PyroCMS used ZendSearch as a driver through this popular Laravel package. However many developers including myself suffered crashes based on Zend's index locking bug. The package was also lacking a zealous leader and frankly my faith was weak in it's future. However PyroCMS must come with out of the box search support.. what to do?

Along came Laravel 5.3 and Scout! A perfect solution and even better yet one that fit tightly in PyroCMS's principles of being transparent and embracing Laravel.

Now searching simply extends the entries function!


{% for result in entries('pages', 'pages').search(request_get('q')).get() %}

    <h3>{{ html_link(result.path, result.title) }}<br>
        <small>{{ url(result.path) }}</small>
    </h3>

    <p>
        {{ result.meta_keywords.labels|join(' ')|raw }}
    </p>

{% endfor %}

By default PyroCMS will use the included TNT Search engine through this driver. You of course are welcome to switch to any driver. Please refer to Scout documentation for more info!

Notifications

Notifications were so ugly in PyroCMS. On top of the unbearable ugliness Pyro's internationalization requirement meant a convoluted overriding of Laravel's mailer and an equally ugly approach to storing translated messages in the message's Twig views for said mailer.

Laravel 5.3 comes with an amazing notification system as well as a mailable trait that replaces the old mailer approach. This means translating messages is super easy and consistent with translating the rest of Pyro / Laravel through translation files. It also means that sending notifications not only by mail but also via Slack, text, or anything else is now natively driver supported through Laravel.

The icing on the cake is the included notification template! Simple sexy notifications out of the box. Nice.

Want to read more on Laravel notifications? Check out the documentation.

Upgrading

Before I get into the upgrade guide please note that while Laravel DOES NOT follow Semantic Versioning PyroCMS DOES and will try to stay as faithful as absolutely possible to it. I will also make it as clear as possible what breaking changes have been inherited from Laravel and which ones have been absorbed into PyroCMS vs which have been fixed and are being softly deprecated through PyroCMS.

On a related note this release marks the mass cleaning of versions, how composer constraints are handled, and managing git-flow going forward. More information on that later.

For more help on migrating from 3.0 to 3.1 head over to the forum!

Backup your entire installation before attempting migration!

On to the upgrade notes:

Base Directories

Upgrades will need to replace/include the following directories and files from 3.1 base installation:

  • composer.json
  • app
  • bootstrap
  • config
  • resources
  • routes
  • tmp

Migrating

After you have the above pulled in you need to run a couple commands.

php artisan migrate --path=vendor/anomaly/streams-platform/migrations/application

php artisan migrate --all-addons

SelfHandling

Laravel 5.2 dropped SelfHandling commands and the interface in general. ALL SelfHandling references should be removed entirely from your addons and have been removed from PyroCMS and it's addons. @handle will be the assumed method where SelfHandling was used outside of commands unless otherwise noted by documentation.

PyroCMS 3.1 comes with a temporary SelfHandling class that will prevent your applications / addons from breaking. It will be removed in 3.2 - be advised! It is located in the tmp folder and autoloaded with the new composer.json file.

Lists Method

The lists method on Laravel's base collection was also removed. pluck should be used instead and has the same signature. The method has been removed from PyroCMS and it's addons.

A lists method has been added to Anomaly\Streams\Platform\Support\Collection in order to softly deprecate it out. The method will be removed in 3.2 - heads up!

Override Directories

Because Laravel is now using the resources folder itself. The previous core directory is being renamed to streams in order to avoid confusion. Simply rename the folder manually and you're all set. Also note the addon:publish and streams:publish commands listed above.

Searchable Models

The search.php module configurations can be deleted and simply add protected $searchable = true; to your custom models if you wish to tie into the new Search system. It's 100% Laravel Scout so please refer to the docs for more information on how to use it. You may also include 'searchable' => true to your migrations and searchable will be added for you.

The {{ search('namespace.stream') }} function has been removed. Please update your search views to the new syntax shown above with entries.

Thanks for all the participation and support! I have a boat load of new addons ready for release on the upcoming PyroCMS store and the forum and documentation module have updates that have been waiting for 3.1 as well.

Enjoy!

- Ryan Thompson