Preface

Introduction

Cartalyst's Platform application provides a very flexible and extensible way of building your custom application.

It gives you a basic installation to get you quick-started with content management, themeable views, application extensions and much more.

Pretty much everything on Platform can be extended and overwritten so you can add your own functionality.

Features

Platform is not just another CMS, it's a starting point for you to build your application providing the tools you need to get the job done as easy as possible.

• Authentication & Authorization
• Role based user management & permissions
• Social Authentication (OAuth, OAuth 2)
• Powerful Theme System
• Powerful Extension System
• Twitter Bootstrap 3.3 ready
• Pages
• Content
• Menus
• Settings
• Tags
• Attributes
• Scaffolding
• Widgets
• Media
• Laravel 4.2

Concepts

The main goal of Platform is flexibility. Platform aims to be as unobtrusive to your application as possible, while providing all the features to make it awesome and save you time.
The app folder is almost identical to a stock-standard Laravel 4 app folder, with a few registered service providers and preset configurations.

The end result? You can continue to make any application you would like without having to conform to Platform "standards" or "practices".

Want to install Platform for an administration area but build a completely custom website? Sure, just start working with app/routes.php as you normally would. Utilize our API, data and extensions where you need, they won't get in your way.

Extensibility

Platform 2 was made to be even more extendable than Platform 1. A number of key files to get you off the ground with extending Platform are:

• app/hooks.php
• app/functions.php
• app/overrides/models.php (1)

• app/overrides/services.php (1)

  (1) You can read more about overrides here.

These files provide a number of templates and boilerplate code for you to override extension classes, hook into system events and add custom logic.

Setup

Requirements

Platform is essentially just a series of components that work with Laravel 4.2. So the requirements are virtually the same. However some components may require dependencies with their own set of minimum requirments.

• PHP >= 5.4.0
• MCrypt PHP Extension

Download Platform

You can get Platform by cloning the repository from GitHub.

git clone -b 2.0 git@github.com:cartalyst/platform.git My_Project

Platform can also be installed by simply downloading a copy from GitHub. After downloading, unzip the .zip file into a location that suits you.

Installing by cloning from the GitHub repository is the preferred method as this gives you an easy way to update Platform by merging changes from the original GitHub repository.

Install Dependencies

After downloading Platform 2, you can install all of Platform's dependencies by running a composer install command in your CLI. Navigate to your Platform folder and run the following command:

composer install

Configure Laravel

Before you can get started with Platform, you'll still have to configure the Laravel 4 framework. Platform is built with Laravel 4 so some configuration is necessary. Please follow all steps detailed in the Laravel 4 configuration documentation.

Permissions

Platform requires the following folders to have write access by the web server:

• The app/config folder (necessary for writing the Platform config files).
• The app/storage folder and its sub-folders.
• The public/cache folder and its sub-folders.
• The public/media folder and its sub-folders.

Install

Platform 2 ships with 2 ways of installation and if required you add your own custom installer.

The CLI Installer

The easiest way to install Platform is to run the CLI installer. Just run the following command and follow all of the steps.

php artisan platform:install

The Browser Installer

You should see the Platform installer when you navigate to the project in your browser. Follow the on screen instructions.

You will need to update the Application URL in app/config/app.php for theme compiling to resolve the font icon dependencies.

Custom Installer

You may also choose to use your own installer by extending ours or completely replacing it.

Platform is an application-base, and thus it is flexible.

If you're distributing an app, you probably don't want a Platform installer for it, you probably want your own installer with your own custom logic.

Just change the requirements in composer.json and register your own installer's service provider.

Basics

Platform 2 isn't just a CMS system. It's a flexible and extensible application which provides a solid base.

By default you can quickly get started by managing users, content and your settings. Creating a new theme is easy and if Platform 2 doesn't provide something you'd like to see, you can easily extend it with your own custom extensions which can be installed through Composer.

This documentation will get you quick-started with Platform 2's basic functionality and will help you build your own custom Platform 2 extensions.

Extensions

Extensions allow you to extend Platform 2 beyond its basic functionality. The
default extensions for Platform 2 are actually composer packages. If you want,
for example, to add a media library, you could add it as a composer package
and after running a composer install, it would get published to the
extensions folder on your Platform 2 application.

Extensions may also be part of your application's repo and not separate composer
packages. They may sit under the extensions or the workbench folder. Be sure to
adjust extensions/.gitignore file for your own needs.

An extension can hold views, controllers, migrations, models, languages files,
anything you'd normally create in the Laravel 4 app directory. This gives
you a nice and convenient way of separating your functionality which you
can later re-use in other applications. Most extensions can be managed
under the operations tab in the Platform 2 admin panel.

Cartalyst's Platform 2 heavily relies on extensions as most of its core functionality
are based on extensions.

Note: All extensions present at the installation time will be installed.
There is no need to modify the installer for any custom extensions you may have.
This makes distributing your own apps or sites that run on Platform 2 a breeze.

Default Extensions

Platform 2 by default ships with a handful of extensions.

Access

Access is an RBAC extension, it combines three extensions (Users, Roles and Permissions) and combined allows you to manage your application Users, Roles and Permissions easily.

You can specify permissions on roles or on users in case a more custom use case appears.

Besides the functionality that this extension provides by default, it comes with a lot of additional functionality powered by Cartalyst Sentinel, a simple and powerful authorization and authentication package which gives you even more functionality to interact with your Users and Roles.

Users

Platform 2 provides some basic user management functionality like adding, editing and deleting users as well as user registration and setting users to an inactive state.

Roles

Because Platform 2 comes with Cartalyst Sentinel installed, you also get easy role management over your users. You can assign users to roles by clicking on the edit button of a user. Later on you can add specific permissions to roles.

Permissions

Permissions can both be set on users and roles. You can assign permissions by editing a user or a role and clicking on the permissions tab.

Here you'll get a listing of all the available permissions for your Platform 2 application.

Permissions are usually added through extensions. You can read more about how to add permissions through extensions here.

Dashboard

The back-end dashboard which comes with the Platform 2 application gives you a good starting point for managing your site. It's a flexible CMS on which you can build your own functionality.

By default the dashboard provides functionality for managing pages, content, users, menus, extensions and your settings. You can add more functionality or alter functionality by adding your own extensions.

Attributes

The attributes extension allows you to create and manage attributes for entities across the application. Features include attribute types (input, radio, select etc.)

Content

Most of the content you create in Platform 2 can be either content stored in the database or in static content files.

Content files are saved in the public/themes/<theme-area>/<theme-name>/views/content folder.

After creating a content file you can create a content entry for it in the Platform 2 back-end.

Re-using Content

Content entries, either static or database driven can be used in views directly by including them with their slug throught the @content('content-entry-slug') method. This method is an extension to the blade templating language specially made to work with Platform 2.

For example, if you have a view called welcome.blade.php for your homepage text and a markdown content file called intro.md which contains an intro text for your application, you can import that intro text into your view with the @content() blade structure.

// welcome.blade.php
<h1>My Platform 2 Website</h1>

@content('intro')

Menus

The menus extension allows you to create and manage menus across your application. Features include conditional visibilities based on roles.

Media

Manage media/files across your application. Features include role-based permissions to access selected media files.

Pages

Just like in a normal CMS you can add pages to your application.

Platform 2 provides support to store the content for these pages in the database or make use of the filesystem to use static view files which are part of your theme.

These static view files can include various content sections and prove to be very dynamic.

You can later re-use these view files in other parts of your application.

Importing Content

You can import content pieces by using the @content() blade structure. This even works with the database type. See Re-using Content in the Content section about how to re-use content parts.

Settings

By default, Platform 2 offers some configuration which you can manage in the settings panel. Add your own settings through your custom extensions.

Themes

Here you can select your currently active front- and back-end theme. Your own custom themes will also appear in these lists. Should you have other theme areas in your extensions, they'll also be listed here.

General Settings

The main settings for your Platform 2 application. Here you can edit your site title and tagline as well as the email settings which your application will be using for sending external e-mails.

Users

The users option panel gives you a couple of user registration options like setting the type of account activation and enabling or disabling user registration.

Pages

The pages settings allows you to choose your default landing page for your application.

Workshop

The workshop settings allows you to set a default author name and email for your extensions. You can also set an optional vendor folder which will be used when generating extensions.

Create Extensions

Because extensions are basically separated app folders there really is no limit to what you can build with them. You could write a media manager extension or a notification handler extension which you can re-use on different Platform 2 applications.

Using The Workshop Extension

Note 1 Workshop requires a workbench directory in the application root. The directory must be writable by the web server.

Note 2 Workshop requires access to composer, if composer is not globally installed or isn't accessible by the web server, you could download composer.phar into your project's main folder in order to use that instead.

The easiest way to get started with an extension is to create one though the Workshop extension. To get started browse to admin/operations/workshop in your Platform 2 back-end.

You'll notice a series of input fields which will be needed to generate your extension files. We'll go over each one of them.

Author name and email

These will be used in your composer.json file under the authors key.

Vendor and Name

These define the namespace for your extension. The Vendor name is a unique identifier like your company or application name. The Name is of course your extension's main name (f.e. Media or Notifications).

Description

Your extension's description.

Dependencies

A list with other extensions on which your extension depends on. List them below eachother as vendor/name.

Prepopulating Components

You can choose to have the Workshop generate some standard files for you like a basic configuration file, some controllers or theme views to get you started with your extension. If you don't want this just leave the checkboxes blank.

Installation

After filling in the fields, you can choose to install your extension automatically or manually.

Automatic install will install the component in the workbench directory in your application root. Make sure the folder exists and is writeable before you attempt this.

Manually Creating Extensions

Manually creating an extensions takes a bit more work. There are two required files for creating extensions: the composer.json file and the extension.php file.

See requirements for more info.

Once your extension has been created, it's time to start adding functionality.

At the heart of your extension is extension.php. This file holds your providers, routes, database seeds, permissions, widgets, settings, menus, and more.

Menus

Menus are defined using a nested array structure. Any menus that you create here are added to the database whenever your extension is installed, sychronized when it's upgraded, and removed when it's uninstalled. Menus that are defined here will be appended to any menus that are defined in the core application when the extension is installed through Platform's extensions interface.

The best way to understand how extension menus work is to study some examples. Platform's Menus extension is the perfect place to start: https://github.com/cartalyst/platform-menus/blob/master/extension.php#L244-L398 . Notice that the top-level array keys match the menu names that are visible in the Platform Menus interface. This is how your extension adds menu items to a given menu. To add a new item to your site's primary navigation, for example, simply modify the menus array accordingly:

'menus' => [

    'main' => [

        [
            'slug' => 'main-customer-service',
            'name' => 'Customer Service',
            'uri' => 'customer-service',
            'children' => [

                [
                    'slug'  => 'main-service-centers',
                    'name'  => 'Service Centers',
                    'uri'   => '#',
                    'class' => 'dropdown-header',
                    'roles' => [
                        'registered',
                    ],

                ],

            ],

        ],

    ],

],

This snippet would add a new "Customer Service" item to the end of the primary navigation menu, which would in turn have one child menu item, "Service Centers".

The key names in the snippet above correspond to the column names in the database, which means that any menu property that can be defined using the Platform interface can also be used here.

Restricting menu visibility to certain roles requires passing the roles key an array of role slugs.

Note It is necessary to uninstall/reinstall an extension for any changes to the menu data in extension.php to become effective. This is because the menu data is added to the database only upon installing the extension. There are buttons at the top of the Extension interface that may be used to perform the uninstall/reinstall.

Note Menu items are disabled as long as the extension is disabled, once enabled, the menu is automatically enabled and vice versa.

Enabling an Extension

After that your extension is added to the extensions folder you can install and enable it through the admin back-end under the operations section. Your extension will be listed amongst the other extensions. Click the edit button to install and enable your extension.

Remember that you can always go back here to disable or uninstall your extension.

Registering Widgets

Widgets can be used to provide small pieces of views which can be easily re-used throughout your application or extension.

If you want to register a small widget but don't want to create a class for it you can do it directly in the extension.php file.

'widgets' => array(
    'foo' => function ()
    {
        // return content.
    }
),

If you'd like to create a separate class for the widget to have some extra functionality you can create a class in the widgets folder. By default, Platform 2 will register your widgets by using your class name as the widget key. You can override this by registering the widget in the extension.php file.

'widgets' => array(
    'foo' => 'My\Widget\Namespace\Foo@someMethod',
),

For more info on creating widgets see the widgets documentation.

Themes

Platform 2 uses Cartalyst's Themes 2 package for managing themes. Because of re-using it, Platform 2 comes with all of the goodness of Themes 2 like asset queuing and compiling. In the documentation below you can find out how to create your own custom themes.

Important Notes

• Default admin and frontend themes are UNTRACKED on git since they're installed using composer. Always, create a new theme and override any views or assets as needed and set your new theme active.
• Default themes are installed through composer, therefore, would get overwritten as soon as an update is found by composer.
• Always modify your extensions' views inside the extension (workbench) and do not modify the published views located under public/themes/:area/:name/extensions/* Published assets are not tracked on git and will be overwritten by the theme publisher as soon as you run its command or automatically run after composer install/update.

Default Themes

Platform 2 ships with 2 default themes, one for each area, Frontend and Admin.

Admin Theme

The default administration theme comes bundled with a lot of goodies, starting from Bootstrap 3.3+, our Data Grid plugin, custom JavaScript functionality to ease you when developing JavaScript scripts etc..

Frontend Theme

The default frontend theme is a bit more simpler, comes bundled with Bootstrap 3.3+, some custom JavaScript functionality, which should give you good head start to build your application :)

Create Themes

You can add different themes to Platform 2 to adjust the look and feel of your application. Themes are located in the public/themes directory. Platform 2 ships with 2 default themes: frontend/default and admin/default. These themes are namespaced in the same order as composer packages in order to prevent naming collisions.

You can add your own theme as long as it's namespaced in the following order: area/my-own-theme. The area being an area for your locations (for example: back-end, front-end, help center, etc...) and your theme name. Add a theme.json file with all the info for your theme. A basic theme.json file should look like this:

{
    "name": "Default Frontend Theme",
    "slug": "frontend::default",
    "description": "The default theme.",
    "author": "Cartalyst LLC",
    "version": "2.0"
}

After creating your theme, you can simply go into the Platform 2 settings and select it as the default theme. You can now also create extension assets specifically for your theme.

Please note that the slug you're adding in the theme.json file needs to be exactly the same as the theme's namespaced folder names.

Theme Assets

Because Platform 2 uses Cartalyst's Themes 2 package it comes with all of the goodness for asset queuing and compiling. More info about using theme assets can be found in the Themes 2 documentation.

Asset Queuing

Add assets for your views by queuing them to be compiled later.

Asset::queue($alias, $path, $dependencies);

Param	Description
$alias	The file alias. This can be used later to indicate asset dependencies.
$path	The path where to locate the alias. You can include a file in the theme's assets folder or use the vendor/packages::path convention to load an external theme's asset file.
$dependencies	Add asset aliases in an array to indicate asset dependencies. These will be loaded then be compiled in a specific sequence so your asset dependencies are loaded before your asset file.

You can also queue .less files and they'll be compiled automatically.

Asset::queue('style', 'css/style.less');

Asset Compiling

When you've queued your assets you can later compile them, for example, in your theme's header. You can use the getCompiledStyles() function to compile style sheets and the getCompiledScripts() function to compile Javascript files.

@foreach (Asset::getCompiledStyles() as $url)
    {{ HTML::style($url) . PHP_EOL }}
@endforeach

Widgets

Widgets are pieces of views which can be re-used throughout your Platform 2 application. An example could be a menu widget for your custom navigation or a Twitter feed widget. Widgets can both be created directly into your app in the app/widgets folder or through extensions.

Creating Widgets

Widgets should best be created in the app/widgets folder. Widgets preferable are stand-alone classes which contain all of the functionality to build pieces of views or content.

For example, you may have a TwitterFeed class widget.

<?php namespace App\Widgets;

class TwitterFeed {

    public function show()
    {
        // custom list with recent twitter messages.
    }

}

Registering Widgets

You can register your widgets anywhere in your application with the Widget::map function. Let's register our twitter feed widget.

Widget::map('twitterfeed', 'App\Widgets\TwitterFeed@show');

Using Widgets

You can use widgets by using the Widget alias and the make function.

echo Widget::make('twitterfeed', $parameters);

Or use the provided blade shortcut.

@widget('twitterfeed', $parameters)

Hooks

Platform 2 hooks are events which are fired at various occasions throughout certain Platform 2 actions.

They give you the oportunity to do something when the event is fired. You can find these hooks in the app/hooks.php file.

Operation Hooks

Hook into the installation / upgrading of your Platform installation. Registered with the Installer::<event> convention.

Event	Description
before	Called before Platform is to be installed
after	Called after Platform has been installed

For example:

Installer::before(function()
{
    // do something.
});

Platform Hooks

Hooks for events of Platform itself. Registered with the Platform::<event> convention.

Event	Description
booting	Before Platform and it's extensions have booted
booted	When everything is setup and ready to roll
ineligible	Whenever Platform cannot run (needs installing etc)

For example:

Platform::booting(function($platform)
{
    // do something
});

Extension Hooks

Hooks for various stages of an Extension's lifecycle. You can access the individual extension properties through $extension->getSlug(). Registered with the Extension::<event> convention.

Event	Description
registering	Before an extension is registered (happens for every extension)
registered	After an extension is registered
booting	Before an installed and enabled extension boots (after all are registered)
booted	After an installed and enabled extension boots
installing	Before an extension is installed
installed	After an extension is installed
uninstalling	Before an extension is uninstalled
uninstalled	After an extension is uninstalled
enabling	Before an extension is enabled
enabled	After an extension is enabled
disabling	Before an extension is disabled
disabled	After an extension is disabled
upgrading	Before an extension is upgraded
upgraded	After an extension is upgraded

For example:

Extension::registering(function(Extension $extension)
{
    // do something.
});

Overrides

Overrides in Platform 2 give you the ability to easily swap core functionality with your own custom functionality.

Route Overrides

Because we use an internal REST API, you have the ability to override any route for an API call to your own logic. This makes extending Platform 2 extremely easy and can be done from anywhere.

To override them open the app/routes.php.

For example, overriding the page slug route.

Route::get('page/{slug}', 'My\Custom\PagesController@show')->where('slug', '.*?');

Model Overrides

The default Platform extensions use the IoC to resolve model instances. You can override these here by simply returning your own model which extends ours.

To override them open the app/overrides/models.php.

For example, overriding the default Platform 2 Content model.

$app['Platform\Content\Models\Content'] = new My\Custom\Models\Content;

Service Overrides

Each Service Provider and Extension registers a number of application services.

To override them open the app/overrides/services.php and customize the behavior of your Platform application.

$app['foo.bar'] = $app->share(function($app)
{
    return new My\Foo\Bar;
});