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 5.0
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 5 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/Http/routes.php
as you normally would. Utilize our API, data and extensions where you need, they won't get in your way.
Extensibility
Platform 3 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 5.0. 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 3.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 3, 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 5 framework. Platform is built with Laravel 5 so some configuration is necessary. Please follow all steps detailed in the Laravel 5 configuration documentation.
Permissions
Platform requires the following folders to have write access by the web server:
- The
config
folder (necessary for writing the Platform config files). - The
public/cache
folder and its sub-folders. - The
public/media
folder and its sub-folders. - The
storage
folder required by Laravel and its sub-folders. - The
vendor
folder required by Laravel.
Install
Platform 3 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
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.
Upgrade
When comes to upgrade Platform to a newer version, you have 2 options, a more manually way, where all the files and folder structure (if applicable) are manually updated or a more automated way, which is by using Git.
This last method brings less work, but it may require a manual validation/patching on some files due to merge conflicts.
The recommended way is by using Git, which is more easier and quick, we also recommend the usage of tools like Git Tower, which simplifies the usage of Git and improves your workflow and also helps this kind of process.
Preparation
Before starting, you need to make sure that your repository has a remote that points to the cartalyst/platform
repository.
To achieve this, we just need to add a new Git Remote.
To add a new remote just run the following on your terminal:
$ git remote add upstream git@github.com:cartalyst/platform
Note: You can change
upstream
to something else, likecartalyst
if you feel it's more easier to remember.
Now that you've the remote added, we can start the upgrade process.
Upgrade to 3.0 from 2.0
Open your terminal and change the current working directory to your local project.
Fetch the branches and their commits from the
upstream
remote.$ git fetch upstream
Check out the branch you wish to merge to. This is the branch that contains Platform 2.0 and by default is called
2.0
.$ git checkout 2.0
Pull the 3.0 branch from the upstream repository. This will keep your commit history.
$ git merge upstream/3.0
If you have conflicts, you'll need to resolve them. You can get more information here.
Commit the merge
You're done :)
Basics
Platform 3 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 3 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 3's basic functionality and will help you build your own custom Platform 3 extensions.
Extensions
Extensions allow you to extend Platform 3 beyond its basic functionality. The
default extensions for Platform 3 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 3 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 5 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 3 admin panel.
Cartalyst's Platform 3 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 3 a breeze.
Default Extensions
Platform 3 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 3 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 3 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 3 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 3 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 3 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 3 back-end.
Re-using Content
Content entries, either static or database driven can be used in views directly by including them with their slug through the @content('content-entry-slug')
method. This method is an extension to the blade templating language specially made to work with Platform 3.
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 3 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 3 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 3 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 3 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 3 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 downloadcomposer.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 3 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 3 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 3 uses Cartalyst's Themes 3 package for managing themes. Because of re-using it, Platform 3 comes with all of the goodness of Themes 3 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 3 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 3 to adjust the look and feel of your application. Themes are located in the public/themes
directory. Platform 3 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 3 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 3 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 3 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 3 hooks are events which are fired at various occasions throughout certain Platform 3 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 3 give you the ability to easily swap core functionality with your own custom functionality. You can override any of the Platform 3 defaults within your own custom extension.
Route Overrides
To override a route defined in another extension, create a custom extension which requires it as a dependency. Within the routes section of extension.php
, any routes you define in your custom extension will take precedent over those defined in the other extension.
Note Routes can also be overriden on any method that is executed after the
PlatformServiceProvider
is booted.
Model and Service Overrides
The default Platform extensions use the IoC to resolve model instances. You can override these models here by simply returning your own model which extends ours or implements the appropriate interface.
Model or Service overrides should be placed in a service provider within a new extension. For example, these are the steps you would take to override the Users model within Platform:
- Create a new custom extension (we'll call it
UserOverride
) in the workbench and definePlatform/Access
andPlatform/Users
as dependencies. - Within the extension, create
src/Providers/UserOverrideServiceProvider.php
and add'Platform\Useroverride\Providers\UserOverrideServiceProvider'
to the providers array in extension.php In your new service provider, set the new Users model on the IoC instance:
public function boot() { $this->app['sentinel.users']->setModel('My\Custom\Models\User'); }
Within your custom service provider, you can also override service bindings like this:
$app['foo.bar'] = $app->share(function($app)
{
return new My\Foo\Bar;
});
Tutorials
Installable Themes
Platform themes can be installed from their own repositories. This allows you to reuse your own themes from project to project. Heres how you do it.
1. Create or duplicate a theme
Choose which theme area to duplicate. Platform ships with two theme areas. frontend & admin. You can name the repository whatever you like. We follow the convention theme-name-area
https://github.com/cartalyst/theme-default-admin
https://github.com/cartalyst/theme-default-frontend
2. Update your new themes theme.json
file
{
"name": "Default Admin Theme",
"slug": "admin::default",
"description": "The default admin theme.",
"author": "Cartalyst LLC",
"version": "2.0"
}
3. Update your themes composer.json
Platform will automatically install themes using our handy composer-installers package.
Open your themes composer.json
and update the following values.
"name": "vendor/area-name",
"type": "platform-theme",
Setting the type to platform-theme
tells platform that the repository is a theme to be installed to specific location.
The part after your vendor name is the directory structure for where the theme will be installed.
"name": "foo/bar-bat",
would install your theme to public/themes/bar/bat
. If your simply creating a new platform admin theme you'd name it something like "name": "acme/admin-custom"
and would be installed in public/themes/admin/custom
Note: Installing repositories to any location is a breeze with our composer-installer package. Check out where the magic happens for themes. ThemeInstaller.php
4. Hosting your theme
You'll need to host your extension as a VCS
repository (https://getcomposer.org/doc/05-repositories.md#vcs) or using Satis (https://getcomposer.org/doc/05-repositories.md#satis)
VCS
You can add a vcs repository to your composer.json
file as follows
"repositories": [
{
"type": "vcs",
"url": ":repository_url"
}
]
Satis
Adding a satis repository works similar to the cartalyst repository located on our theme's composer.json
files.
"repositories": [
{
"type": "composer",
"url": "satis_url"
}
]
5. Update your platform composer.json
file
Require your newly created theme just below our default themes in your Cartalyst Platform composer.json
file.
"require": {
...
...
"acme/admin-custom": "dev-master"
}
Voila! Run composer install
and your new theme should appear in the themes directory as described in step 3.
Code well, rock on!
Extending Extensions
To override/extend logic from an existing extension would be to create a new extension and start overriding any logic needed on there.
- Create a new extension
:vendor/:extension
- Add
platform/:extension
to the require array onextension.php
to ensure the the new extension is registered, booted and installed afterplatform/:extension
.
Note
:vendor
,:Vendor
used on this page refer to your custom vendor name,:extension
,:Extension
refer to the extension in question.
Overriding the model
- Create a new service provider and add it to the providers array on
extension.php
and add the following code to theregister
method of your new service provider. - Create a new model. (can extend the default model)
$this->app->bind('Platform\:Extension\Models\:Model', ':yourModel');
Overriding a controller
Overriding a controller requires re-defining the routes to point to the new controller.
- Create a new controller that extends the default controller under your extension.
- Override or add new methods to the new controller.
- Redefine the routes you want to be handled by your new controller on
extension.php
and make sure to reference your new controller.
Example
The code below will override the /
routes (GET, POST) to use the new controller.
Route::group(['namespace' => ':Vendor\:Extension\Controllers'], function()
{
Route::group([
'prefix' => admin_uri().'/:extension',
'namespace' => 'Admin',
], function()
{
Route::get('/' , ['as' => 'admin.:extension.all', 'uses' => ':ExtensionController@index']);
Route::post('/', ['as' => 'admin.:extension.all', 'uses' => ':ExtensionController@executeAction']);
});
});
Overriding repositories, event and data handlers, or validators
Overriding repositories, event handlers or data handlers requires overriding their binding in the IoC container.
Default bindings
- Repository -
platform.:extension
- DataHandler -
platform.:extension.handler.data
- EventHandler -
platform.:extension.handler.event
- Validator -
platform.:extension.validator
Example
Overriding the UserRepository
would require overriding the offset platform.users
by adding the following code to the provider's register
method of your new extension.
$this->app->bind('platform.users', ':Vendor\Users\Repositories\UserRepository');
Voila! You've successfully extended a Platform extension.
Code well, rock on!