Installation

This section will go over what you need to install PyroCMS and how to do it.

Heads Up: Looking for documentation on developing with PyroCMS? Have a look at documentation for Pyro's engine, the Streams Platform.

Server Requirements

PyroCMS has a few system requirements:

PHP >= 5.6.4

PDO PHP Extension

cURL PHP Extension

SQLite PHP Extension

OpenSSL PHP Extension

Mbstring PHP Extension

Fileinfo PHP Extension

Tokenizer PHP Extension

GD Library (>=2.0) OR Imagick PHP extension (>=6.5.7)

Installing PyroCMS

PyroCMS utilizes Composer to manage its dependencies. So, before using PyroCMS, make sure you have Composer installed on your machine.

Heads Up: Do not create a .env file just yet - Pyro's installer will generate one for you.

Install with Composer

You may install PyroCMS by issuing the Composer create-project command in your terminal:

composer create-project pyrocms/pyrocms

If you are using a Windows environment, you might run into issues with the length of paths when unzipping packages. To avoid this issue, use the --prefer-source flag.

Running the Installer

After downloading and installing PyroCMS and it's dependencies, you will need to install the software in order to get started. By this time you should be able to visit your site's URL which will redirect you to the installer.

Directory Permissions

After installing, you may need to configure some permissions in order to proceed. Directories within the storage, public/app, and the bootstrap/cache directories should be writable by your web server. If you are using the Homestead virtual machine, these permissions should already be set.

If, when trying to access the installer below, you get a white screen. Your permissions are misconfigured.

Post Installation

Upon logging in the first time after installation you will notice the suggestion to delete the Installer module. To do this simply remove the "anomaly/installer-module" requirement from your project's composer.json file and run composer update.

If you are not using composer going forward you can simply delete /core/anomaly/installer-module from your Pyro installation.

Contributing

This section will go over how to contribute to PyroCMS, addons, and it's components.

Bug Reports

To encourage active collaboration, pull requests are strongly encouraged, not just bug reports. "Bug reports" may also be sent in the form of a pull request.

However, if you file a bug report, your issue should contain a title and a clear, detailed description of the issue. You should include as much relevant information as possible and a code sample or link to your repository that demonstrates the issue. The goal of a bug report is to make it easy for yourself - and others - to replicate the bug and develop a fix quickly.

Remember, bug reports are created in the hope that others with the same problem will be able to collaborate with you on solving it. Do not expect that the bug report will automatically see any activity or that others will jump to fix it. Creating a bug report serves to help yourself and others start on the path of fixing the problem you are experiencing.

Please submit all bug reports to the [http://github.com/pyrocms/pyrocms](PyroCMS repository). All pull requests must be submitted to the applicable addon repository.

When submitting bug reports for other addons to the PyroCMS repository please prefix the repository the bug report is for by prefixing it with the application addon.

[streams-platform] Your bug report title here.

Development Discussion

Discussion regarding bugs, new features, and implementation of existing features should take place on the [http://pyrocms.com/forum](PyroCMS forum). Discussion can also be had in the PyroCMS Slack team. Ryan Thompson, the lead developer, is typically present in the channel on weekdays from 10am-4pm (UTC-06:00 or America/Chicago).

Which Branch?

*All** bug fixes should be sent to the latest stable branch. Bug fixes should never be sent to the master branch unless no develop branch exists for whatever reason.

Minor features that are fully backwards compatible with the current release may be sent to the latest stable branch.

Major new features should always be sent to the develop branch, which contains upcoming releases.

If you are unsure if your feature qualifies as a major or minor, please ask ryanthompson in the #generalPyroCMS Slack channel.

Security Vulnerabilities

If you discover a security vulnerability within PyroCMS, please send an e-mail to Ryan Thompson at [email protected]. All security vulnerabilities will be promptly addressed.

Coding Style

Streams Platform and all addons follow the PSR-2 coding standard and the PSR-4 autoloading standard.

Structure

This section will go over the general application structure of PyroCMS.

The Addons Directory

The addons directory is where all addons not included in the composer.json file should be kept.

Note: Typically addons in the addons directory are committed to your project repository.

Addon Directory Structure

Just like composer packages PyroCMS addons have a vendor slug that is included in their path. Addons also include the site's application reference and the addon's type in it's full path.

addons/{application}/{vendor}/{addon}-{type}

An example could be:

addons/your_site/anomaly/documentation-module

Sharing Addons Between Applications

All addons in the composer.json file will be available for all applications in your PyroCMS installation.

You can also share addons by placing them in the addons/shared folder.

addons/shared/anomaly/documentation-module

The App Directory

The app directory can be used just like in a native Laravel application. While it is recommended to bundle your application logic in addons the app directory can be used all the same.

For more information on using the app folder for application services please refer to Laravel documentation.

The Bootstrap Directory

The bootstrap directory contains files that bootstrap the framework and configure autoloading. This directory also houses a cache directory which contains framework generated files for performance optimization such as the route and services cache files.

You will notice the bootstrap/app.php file also replaces the console kernel and http kernel with Pyro's own.

The Config Directory

The config directory, as the name implies, contains all of your application's configuration files. It's a great idea to read through all of these files and familiarize yourself with all of the options available to you.

You will notice a streams.php configuration file that can be used to alter the boot process of the Streams Platform, the engine of PyroCMS.

For configuring addons and the Streams Platform further please refer to [#configuration](configuration section).

The Core Directory

The core directory contains any addon required by your composer.json file. Any file contained in the composer.json dependencies is considered part of your website or application's core dependencies.

Warning: It is not advised to commit your core directory!

The Database Directory

The database directory works exactly the same as a native Laravel application. Because most migrations and seeds are within addons, it can be helpful to put miscellaneous seeds and migrations in the database directory.

The Public Directory

The public directory contains the index.php file, which is the entry point for all requests entering your application. This directory also houses your assets such as images, JavaScript, and CSS.

The Asset service in the [/documentation/streams-platform](Streams Platform) also uses the public directory to cache images and assets from various themes and addons. Cached assets can be found in the public/app/{application}/assets directory.

The Resources Directory

The resources directory contains Laravel views as well as raw, un-compiled Laravel assets such as LESS, SASS, or JavaScript. This directory also houses all of your language files.

While you can use the resources directory exactly like you would in a native Laravel application you are encouraged to bundle language files, assets, and views in their respective addons that you are developing for your website or application.

Note: It is highly encouraged to bundle your resources into their respective addons that you develop.

The resources directory will also contain override files for addon config, views, and language files. You will be published to the resources/{application}/addons directory then when running the corresponding Artisan commands.

The Routes Directory

The routes directory contains all of the route definitions for your application. By default, three route files are included with Laravel: web.php, api.php, and console.php.

Note: It is highly encouraged to bundle your routes into their respective addons that you develop.

The web.php file contains routes that the RouteServiceProvider places in the web middleware group, which provides session state, CSRF protection, and cookie encryption. If your application does not offer a stateless, RESTful API, all of your routes will most likely be defined in the web.php file.

The api.php file contains routes that the RouteServiceProvider places in the api middleware group, which provides rate limiting. These routes are intended to be stateless, so requests entering the application through these routes are intended to be authenticated via tokens and will not have access to session state.

The console.php file is where you may define all of your Closure based console commands. Each Closure is bound to a command instance allowing a simple approach to interacting with each command's IO methods. Even though this file does not define HTTP routes, it defines console based entry points (routes) into your application.

Pro Tip: These routes are loaded FIRST. This means that duplicate subsequent routes will override them by name and route path.

The Storage Directory

The storage directory contains your compiled Twig and Blade templates, file based sessions, file caches, and other files generated by the framework. This directory is segregated into app, framework, logs, and streams directories. The app directory may be used to store any files generated by your application. The framework directory is used to store framework generated files and caches. The logs directory contains your application's log files. And finally, the streams directory contains your stream generated entry models, addon caches, and private storage (non-public uploads for example).

The storage/app/public directory may be used to store user-generated files, such as profile avatars, that should be publicly accessible. You should create a symbolic link at public/storage which points to this directory. You may create the link using the php artisan storage:link command.

The Vendor Directory

Configuration

This section will describe how configuration works in PyroCMS and how to access it. For the most part configuration in PyroCMS works exactly the same as [https://laravel.com/docs/5.3/configuration](configuration in Laravel).

Accessing Configuration

You may easily access your configuration values using the global config helper function from anywhere in your application. The configuration values may be accessed using "dot" syntax, which includes the name of the file and option you wish to access. A default value may also be specified and will be returned if the configuration option does not exist:

$value = config('app.timezone');

To set configuration values at runtime, pass an array to the config helper:

config(['app.timezone' => 'America/Chicago']);

Streams Platform Configuration

The Streams Platform contains it's own configuration. You may easily access configuration values for the Streams Platform just the same as you would any other configuration. Configuration values for the Streams Platform have a streams:: prefix:

$value = config('streams::locales.default');

To set configuration values at runtime, pass an array to the config helper:

config(['streams::assets.paths.my_path' => 'my/example/path']);

Publishing streams configuration

In order to configure the Streams Platform without modifying core files you will need to publish the Streams Platform with the following command:

php artisan streams:publish

You can then find the Streams Platform configuration files in resources/{application}/streams/config.

Addon Configuration

Addons contain their own configuration. You may easily access configuration values for addons just the same as you would any other configuration. Configuration values for addons have a vendor.type.slug:: prefix based on their dot namespace:

$value = config('anomaly.module.users::config.login');

To set configuration values at runtime, pass an array to the config helper:

config(['anomaly.module.users::config.login' => 'username']);

Publishing addon configuration

In order to configure addons without modifying core files you will need to publish the addon with the following command:

php artisan addon:publish vendor.type.slug

You can then find the addon configuration files in resources/{application}/{vendor}/{slug}-{type}/config.

Errors & Logging

When you start a new PyroCMS project, error and exception handling is already configured for you through Laravel's default provisions.

For logging, Laravel utilizes the Monolog library, which provides support for a variety of powerful log handlers. Laravel configures several of these handlers for you, allowing you to choose between a single log file, rotating log files, or writing error information to the system log.

Configuration

This section will describe how to configure error logging for Pyro.

Error Detail

The debug option in your config/app.php configuration file determines how much information about an error is actually displayed to the user. By default, this option is set to respect the value of the APP_DEBUG environment variable, which is stored in your .env file.

For local development, you should set the APP_DEBUG environment variable to true. In your production environment, this value should always be false. If the value is set to true in production, you risk exposing sensitive configuration values to your application's end users.

Log Storage

Out of the box, PyroCMS supports writing log information exactly like Laravel. You can write to single files, daily files, the syslog, and the errorlog. To configure which storage mechanism Laravel uses, you should modify the log option in your config/app.php configuration file. For example, if you wish to use daily log files instead of a single file, you should set the log value in your app configuration file to daily:

'log' => 'daily'

Maximum Daily Log Files

When using the daily log mode, PyroCMS will only retain five days of log files by default. If you want to adjust the number of retained files, you may add a log_max_files configuration value to your app configuration file:

'log_max_files' => 30

Log Severity Levels

When using Monolog, log messages may have different levels of severity. By default, PyroCMS writes all log levels to storage. However, in your production environment, you may wish to configure the minimum severity that should be logged by adding the log_level option to your app.php configuration file.

Once this option has been configured, Laravel will log all levels greater than or equal to the specified severity. For example, a default log_level of error will log error, critical, alert, and emergency messages:

'log_level' => env('APP_LOG_LEVEL', 'error'),

Monolog recognizes the following severity levels - from least severe to most severe:

debug

info

notice

warning

error

critical

alert

emergency

Custom Exceptions

By default PyroCMS load the corresponding view from the Streams Platform matching the error code thrown when debugging is disabled.

For example if the system throws a 500 error and is not in debug mode then the streams::errors/500 view will be loaded.

You can override these views a few different ways.

Publishing Streams Views

You can publish the entire Streams Platform resources by running the following command:

php artisan streams:publish

You can then customize the resources/views/errors views to accommodate your needs.