cookbook lol 101

8/17/2019 Cookbook lol 101

http://slidepdf.com/reader/full/cookbook-lol-101 1/20



0

1

1.1

1.2

1.3

1.4

2

3

4

5

6

6.1

7

8

8.1

Table of Contents

Introduction

Installation

Downloading Via Composer

Homestead

Installing Orchestra Platform

Sync Application Skeleton

Development Environment

Routing

HTML Supports

Extensions

Themes

Distributed Themes via Composer

Deploying Orchestra Platform

Tips and Tricks

Disable Normal User From Accessing Backend

Orchestra Platform Cookbook

2



Introduction

Orchestra Platform provide a solid base boilerplate to build your new web applications. It's

not a CMS. Instead, it's a springboard to build most of the tools you wish you had available

for projects that you're working on but never took the time to build.

Have you had a client that wanted you to create a custom application but at the same time

they're also looking to have a robust Content Management System within that same

application? If you answered yes, what are your options?

To build the application on top of WordPress (or other CMS system that you're familiar

with).

To build the application using your favorite language and framework while also

integrating your own custom-built CMS components in it hoping that it's easy for your

clients to use (just like how they were to use WordPress easily!).

Or try to integrate both (which you know would be a bad idea from the start).

Orchestra Platform will solve this problem by creating a similar Administration Panel as you

would see in WordPress wp-admin, so you can continue writing awesome code in Laravel

but at the same time have CMS components ready at your disposal.

About the Cookbook

This cookbook is aim to help developers to learn and use Orchestra Platform 3. We once try

writing in-depth tutorial on Orchestra Platform but feel that it quickly become obsolete once

we release new version.

We're however hoping that by hosting this book via GitBook and the source markdown in

GitHub it would be easier to for us to update this cookbook in the future.

Contributing

You, the community are more than welcome to contribute anything to this book by forking

and submitting Pull Request. The source of this book is available at

https://github.com/orchestral/cookbook.


3Introduction

https://github.com/orchestral/cookbook

https://github.com/orchestral/cookbook

https://github.com/

https://gitbook.com/



Installation

Getting started with Orchestra Platform 3 is as much identical to getting started with

Orchestra Platform 2. Therefore you need to have some minimum knowledge on Laravel 5,

Composer and Packagist.

I would highly recommend watching Laravel 5 Fundamentals and What's New in Laravel 5.1

video series from Laracasts in order to get familiar with Laravel 5 to understand some of the

approach we use in Orchestra Platform 3.

Requirements

To be involved with the code exercise that we going to use in this cookbook please ensure

that your local machine have the following requirements:

PHP 5.5.9+

OpenSSL Support

Composer

VirtualBox

Vagrant

NPM


4Installation

http://www.vagrantup.com/downloads.html

https://docs.npmjs.com/getting-started/installing-node

http://www.vagrantup.com/downloads.html

https://www.virtualbox.org/wiki/Downloads

https://getcomposer.org/doc/00-intro.md

https://laracasts.com/

https://laracasts.com/series/whats-new-in-laravel-5-1

https://laracasts.com/series/laravel-5-fundamentals

https://packagist.org/

https://getcomposer.org/

http://laravel.com/



Downloading Via Composer

Firstly, run the following command to download Orchestra Platform 3 using Composer:

$ composer create-project orchestra/platform patio "3.1.x" --prefer-dist

This composer command would create a new project for you on patio folder using the

latest development build, --prefer-dist is another option that you can use to indicate that

you want to download a distributed version instead of cloning the repository, otherwise use

--prefer-source .

Once composer finish installing the dependencies you can navigate the project directory.

$ cd patio

To test that everything is working, you may use the Serve command:

$ php artisan serve

Laravel development server started on http://localhost:8000/

Now open http://localhost:8000 and you should see our splash screen.


5Downloading Via Composer

http://localhost:8000/



Homestead

This process is optional, but I highly recommend doing it for developing Orchestra Platform

on your local mashine. Homestead give you full access to feature that we can use with

Orchestra Platform. You can read the full documentation from Laravel Homestead.

Now, if you haven't use Homestead before, you probably need to add the box:

vagrant box add laravel/homestead

Once you have it downloaded, let run the following command in your project directory.

composer require --dev "laravel/homestead=^2.1"

Once composer has installed the dependencies, you can start adding Homestead support

for your project by running the following command:

./vendor/bin/homestead make

This action will create Vagrantfile and Homestead.yaml on your project root directory.

Update Homestead.yaml

The generated Homestead.yaml will generally good enough to get you started, but let's open

it and inspect the following:

Key Description

ip Ensure that ip is unique and is not being use by other VM or machine in

your intranet.

hostname You can either use the default or customize it based on your preferences.

name You can either use the default or customize it based on your preferences.

sites Make sure you map all the possible domain for your application.

databases Make sure you type in the database name that you want to use for your

application.

Here's an example how I configured it on my machine.


6Homestead

http://laravel.com/docs/5.1/homestead



---

ip: "192.168.50.10"

memory: 2048

cpus: 1

hostname: patio

name: patio

provider: virtualbox

authorize: ~/.ssh/id_rsa.pub

keys:

- ~/.ssh/id_rsa

folders:

- map: "/Users/crynobone/Sites/patio"

to: "/home/vagrant/patio"

sites:

- map: patio.app

to: "/home/vagrant/patio/public"

databases:

- patio

variables:

- key: APP_ENV

value: local

- key: DB_DATABASE

value: patio

- key: CACHE_DRIVER

value: redis

- key: SESSION_DRIVER

value: redis

Also take note changes made under variables . This as identical to modifying .env .

Provision VMNow we can start provisioning the VM.

vagrant up

Update the Hosts File

Don't forget to add the "domains" for your Nginx sites to the hosts file on your machine! The

hosts file will redirect your requests for the local domains into your Homestead environment.

On Mac and Linux, this file is located at /etc/hosts . On Windows, it is located at


7Homestead



C:\Windows\System32\drivers\etc\hosts . The lines you add to this file will look like the

following:

192.168.50.10 patio.app

Once you have added the domain to your hosts file, you can access http://patio.app via your

web browser!


8Homestead

http://patio.app/



Installing Orchestra Platform

To start the installation, navigate to http://patio.app/admin.

Check Requirement

This page in general allows you to see if there any unfulfilled requirement that would

disallow you from using Orchestra Platform properly.

You should be able to install if you have configure everything properly.

Create Administrator User


9Installing Orchestra Platform

http://patio.app/admin



The installation is keep to minimum, for initial installation you would just need to key-in your

e-mail address, full name and a password. You can also pick a name for the current

application. For this project I picked "Playground".

Done

The installation is just that simple. On later chapter we would look at how we can hook into

Laravel event system to customize the first installation for project that requires it.





Now if you try to access http://patio.app/admin again, you'll see a login page instead of the

installation wizard.



http://patio.app/admin



Sync application skeleton

Disclaimer: This is an advanced method to keep your application up to date with

upstream. However you can skip this part if you not to familiar with Git or merging

conflict.

Most of the time, keeping the application skeleton up to date with orchestra/platform is such

a PITA. I would recommend doing the following if you're using GIT as your source control.

First, if you already commit added your project to Git, you need to create an orphan branch

so we can have a clean branch that we stage merging updates from orchestra/platform

when we fetch updates.

$ git checkout --orphan skeleton

Next, let's commit our base skeleton.

$ git commit -sam "Initial base skeleton"

Now, let's add orchestra/platform as a remote.

$ git remote add orchestra [email protected]:orchestral/platform.git

Before fetching the remote, we should disable fetching tags. You can set this permanently

per project via:

$ git config remote.orchestra.tagopt --no-tags

You should also disable pushing any changes to orchestra remote.

$ git remote set-url --push orchestra no_push

Fetching updates

Once everything is ready, we can start fetching the remote:

$ git fetch orchestra


12Sync Application Skeleton

https://github.com/orchestral/platform



Merge updates

To merge updates, it better to use --squash to merge all changes into single commit.

$ git merge --squash orchestra/3.1

If you happen to see the following:

➜ patio git:skeleton ✓ gm --squash orchestra/3.1

error: The following untracked working tree files would be overwritten by merge:

public/packages/.gitkeep

Please move or remove them before you can merge.

Aborting

Just delete the file and you're set to go

$ rm public/packages/.gitkeep

Let's try again:

➜ patio git:skeleton ✓ gm --squash orchestra/3.1

Auto-merging resources/config/auth.php

CONFLICT (add/add): Merge conflict in resources/config/auth.php

Auto-merging composer.json

CONFLICT (add/add): Merge conflict in composer.json

Squash commit -- not updating HEAD

Automatic merge failed; fix conflicts and then commit the result.

Two files has merge conflict, this is typical when you're using this approach (which is why it's

mark as advanced). Manually merge the conflict and commit the code.

$ git add .

$ git commit -sam "Update skeleton (with update to ...)"

As an example:

➜ patio git:skeleton ✗ gc -sam "Update skeleton with update to auth config"

[skeleton 5002b82] Update skeleton with update to auth config

5 files changed, 359 insertions(+)

create mode 100644 .travis.yml

create mode 100644 docs/changes.md

create mode 100644 public/packages/.gitkeep create mode 100644 readme.md





You might see that this approach also add .travis.yml , docs/changes.md and readme.md .

You can either keep this file or remove it

$ git rm .travis.yml docs/changes.md readme.md

$ git commit -sam "Remove irrelevant skeleton files"

Do remember each time we merge orchestra remote, these files will also be included.

Applying changes to your code

Now, remember skeleton branch is an orphan branch. We would need to merge this

changes to our working branch:

$ git checkout master

$ git merge skeleton

Again, solve any merge conflict that could happen when merging.





Development Environment

Before we start writing any code, let's prepare our installation for development by installing

Studio Component. Studio component provide set of command to generate relevant files for

your project. This would help reduce the development time needed to build the application.

$ composer require --dev "orchestra/studio=~3.1"

Setup Local Environment

Now, as we all know --dev dependency is typically not available when we deploy to

production, as this would minimize the amount of packages need to be pull for production. In

order to register the component only for development usage let's create a new app.php

configuration file for local environment.

$ cd resources/config

$ mkdir local

$ cd local

$ touch app.php

This would just create a new file at resources/config/local/app.php

Now let's add the service provider:

<?php

return [

'providers' => append_config([

Orchestra\Studio\StudioServiceProvider::class,

]),

];

This would mean that Orchestra\Studio\StudioServiceProvider will only be loaded when we

user "local" environment.

Checking Installation Status

You can now view the available command from php artisan :


15Development Environment

https://github.com/orchestral/studio



key

make:auth-controller Create auth boilerplate controllers and views

make:contract Create a new Contract interface

make:filter Create a new Filter class

make:menu Create a new Menu handler class

make:validator Create a new Validator handler class


16Development Environment



Themes

Themes are available by default on every Orchestra Platform installation and separated into

two group;

Frontend

Backend

Managing Themes

You can either manage themes via Artisan or Control extension.

Artisan

theme

theme:activate Set active themes in the application.

theme:detect Detect available themes in the application.

theme:optimize Pre-cache themes views in the application.

php artisan theme:activate

php artisan theme:detect

You can review this by running php artisan theme:detect from your working directory:

$ php artisan theme:detect

+----------+------------+----------+---------+

| ID | Theme Name | Frontend | Backend |

+----------+------------+----------+---------+

| default | Default | ✓ | ✓ |

+----------+------------+----------+---------+

php artisan theme:optimize

Control Extension


17Themes



Distributed Themes via Composer

Wouldn't it be nice if we can install theme as simple as installing new packages (for Laravel

etc).

$ composer require "stackie/adminlte-theme=^0.1"

This is available for Orchestra Platform, in fact you as the user can install AdminLTE theme

for Orchestra Platform using the above command. Once you have done that you can run the

following command.

$ php artisan theme:detect+----------+------------+----------+---------+

| ID | Theme Name | Frontend | Backend |

+----------+------------+----------+---------+

| adminlte | Admin LTE | ✗ | |

| default | Default | ✓ | ✓ |

+----------+------------+----------+---------+

And activate the theme via:

$ php artisan theme:activate backend adminlte

Theme [Admin LTE] activated on group [backend].

Creating a New Theme

In this chapter, we will look at building a simple theme for Orchestra Platform. First let's

create a new theme project and make it available for patio .

$ mkdir mini-theme$ cd mini-theme

Once we're inside the folder, you can easily use composer init to start building the theme's

composer.json file.


18Distributed Themes via Composer



Disable normal user from using the backend

There might be situation where you actually want to avoid normal user from accessing the

backend. This can be done by including the following snippet in your AppServiceProvider

etc.

Foundation::when('orchestra::*', function () {

if (Auth::isNot('Administrator')) {

abort(403, 'Not authorized to be here!');

}

});

Foundation::when() would trigger the callback when the request match Orchestra PlatformURL routing when router.matched event is triggered.

You can also modify the response object by type-hinting to kernel.handled event, to do so

let's use Foundation::whenOn() instead:

use Illuminate\Http\Request;

use Illuminate\Http\Response;

Foundation::whenOn('orchestra::*', 'kernel.handled', function (Request $req, Response $re

$resp->headers->set('X-BUILT-WITH', 'Orchestra Platform');

});

Do note that the kernel.handled is execute after a response is return from Laravel

middleware.


cookbook lol 101

Documents