Download the PHP package neemzy/patchwork without Composer

Patchwork

Patchwork is a PHP 5.4+ full-stack web framework, which main purpose is to provide a minimalist yet complete start point for building websites.

Table of contents

• Philosophy
• Round table
• Structure and installation
• Directory structure
• Bootstrap file
• Back-end development
• Front-end development
• Testing
• Deployment
• Credits

Philosophy

Patchwork aims at solving one subset of web development: building small to medium-sized websites for equivalent corporations, should they only display data in a nice way or offer some more user interaction, like a blog or an online shop. When large frameworks are way too heavy for the task and old-school CMS do not provide the flexibility you need, Patchwork comes to the rescue.

Instead of providing yet another incomplete solution to every problem, Patchwork gathers together the best web development tools available and takes care of the boilerplate code. Define your data model, set up your business logic, polish the UI and make your clients happy in a breeze.

Patchwork has been crafted throughout many projects among the lines of the above, and will keep evolving the same way: pragmatic, simple, pleasant to use, and damn efficient.

Round table

Package management

• Composer: the now standard package manager for PHP.

• NPM: node.js's package manager, which is used to install front-end dependencies.

Back-end

• Silex: a micro-framework built around Symfony components, which provides a dependency injection container and a basic web application structure. It comes in Patchwork along with multiple service providers.

• Twig: Symfony's de facto templating engine, used by default in Silex. It comes in Patchwork along with multiple extensions.

• Swift Mailer: Symfony's de facto mail sender, used by default in Silex.

• RedBean: an ORM which particularity is that it creates your database schema itself as you write code. Its integration with Silex is handled by a dedicated service provider, in order to make it available as an instance rather than a static facade.

• Monolog: the standard logger for PHP.

• Environ: an environment manager which allows defining environments triggered by a boolean callback (typically based on hostname detection) and executing environment-specific code.

• Image Workshop: an image library used for resizing and cropping images.

• PHPUnit: one of the major unit testing tools for PHP.

Front-end

• gulp: a task runner for asset processing and optimization, which allows for live compilation and reloading during development. Along with the libraries listed below, it makes use of Autoprefixer, CSSO, JSHint, [UglifyJS]() and image minification and font conversion utilities.

• LESS: a CSS preprocessor.

• Browserify: a front-end JavaScript dependency manager, which allows using CommonJS's require method to help keep a good code structure.

• Bootstrap: Twitter's HTML/CSS framework, powered by LESS and used to build back-office user interfaces.

• Behat and Mink: functional tests tools, that can pilot a browser to use your app. Running JavaScript-capable tests will require the use of Selenium and PhantomJS.

Structure and installation

All code that could possibly handle inheritance/dispatching in one way or another (which includes PHP classes, basic LESS stylesheets and NicEdit, a JavaScript WYSIWYG editor) is contained into the framework's core, available as a separate package. The framework's repository itself is mainly a sample app - about pizzas - designed to help you getting started quickly.

The best way to start is to use Composer, which will clone that repository and install all required dependencies (make sure Composer and NPM are installed first):

After installing dependencies, the installer will ask you if you want to remove Git history from the repository. You want to agree to that, since you are building your own project and not contributing to this one!

You then have to check a few steps:

• var/db and var/log should be writable by your web server's user.
• Your web server/virtual host should be configured right. A sample .htaccess file is provided in the public directory, if by any chance you use Apache.
• For development, gulp should be installed globally (npm install -g gulp).
• For development as well, SQLite and the corresponding PHP extension should be installed (sudo apt-get install sqlite php5-sqlite on Debian and Ubuntu).

At this point, you may want to adapt some configuration settings:

• Set your app's root URL in gulpfile.js and behat.yml.
• Define your project's PHP namespace in composer.json and app/config/settings/common.yml.
• In the latter file, edit your app's title and short description.

Finally, run gulp at the application's root to have your browser open at the URL you have chosen above and a livereload server started, and start coding!

Directory structure

This is a quick tour around Patchwork's directory structure, in order to take a first glance at how it works. The following represents the directory structure's state as of installation, and is by no mean an obligation to follow it in its deepest details, as most of it can be set up differently through appropriate configuration:

Bootstrap file

Patchwork's main file is located at app/bootstrap.php. This file is included by public/index.php in order to bootstrap the Silex application, which the latter then runs. It is responsible to service and controller binding as well as some extra configuration.

Note that topics explained below are, for the most part, already pre-configured in the initial setup, and are detailed here for clarity purposes (helping you tweak them to suit your needs).

Setting your application's base path

Use $app['base_path'] = dirname(__DIR__); to expose your app's base path (FileModel needs it for file uploads).

Defining environments

Register an instance of Neemzy\Silex\Provider\EnvironServiceProvider to your Silex app and feed it Environment instances:

In the sample setup, the prod environment binds an error handler to the app (that renders error pages with the app/views/front/partials/error.twig template) and uses ETags to create request cache. It also disables the $app['debug'] parameter.

Configuration

Config parameters are read from YAML files read from app/config/settings, the best practice being to define one file per environment (see above) that all include and extend a common.yml file if required.

It will then all be available through $app['config'], adding an array dimension for every configuration level:

Translations

Translations are also read from YAML files, this time coming from app/config/i18n. As they are fed to an instance of Symfony\Component\Translation\Translator, they eventually belong to a specific domain (allowing Silex to automatically fetch them for translating validation error messages or date formatting, among other things). Patchwork thus allows you to easily get your translations loaded correctly, by naming your files [domain].[locale].yml, e.g. validators.fr.yml.

A file name without a domain (like en.yml) will be loaded to the default domain, and may serve for generic translations.

Back-end development

Views

Views are handled by Twig. The main thing to remember is that your application is accessible in templates through the app variable, which will let you expose pretty much anything you may need. Twig extensions are also defined in app/bootstrap.php.

The recommended directory structure for your app/views directory looks like this:

Twig manual

Asset paths

Patchwork brings in Simple Twig Asset Extension:

Models

Model classes (located at app/src/Model) must extend Neemzy\Patchwork\Model\Entity. See app/src/Model/Pizza.php for a short yet working example.

RedBean

The Entity class itself extends RedBean_SimpleModel, empowering your models with ORM functionalities. Table names in database are thus the same as your classes' names (lowercased).

RedBean's configuration (including connection informations as well as model class namespacing) is done in the service provider's registration in app/bootstrap.php.

RedBean manual

Validation

Validation constraints are defined through public static function loadValidatorMetadata(ClassMetadata $metadata). You must use getter constraints and define getters for your model's members accordingly, as no properties shall be directly defined (in order to let RedBean's catch-all getter do its magic). Doing so also allows you to keep control over the validated data:

Symfony validation manual

Traits

Patchwork uses a poor man's event dispatching system through PHP traits in order to share common entity functionality. It works by enabling the possibility of dispatching a method call among the class's used traits, through an eponymous method:

As you understood, methods called by dispatch are typically brought in by traits but remain overrideable by the target class if required.

Some traits are available out of the box but you can roll out your own if required.

FileModel

This trait enables support for files:

• Upon file upload (if one of the model's fields contains an instance of Symfony\Component\HttpFoundation\File\UploadedFile), moves it to a permanent location and generate its name if validated
• Upon model deletion, deletes related files

File fields getters in your models should expose the file's full path, but returning $this->getFilePath($field, true);

ImageModel

This trait extends FileModel (which should no more be used in your model once you use this one) and adds automatic image resizing support by detecting MaxWidth and MaxHeight validation constraints.

SlugModel

This trait adds a slug field to your models, which contains an URL-valid identifier based on the return of the getSluggable method, or the table name appended with the id if the latter yields an empty string (which is its default behavior):

It also exposes a slugify method to regenerate the slug if the data it relies on has changed but the model hasn't been updated yet.

SortableModel

This trait adds a position field to your models, which get automatically calculated upon insertion, deletion (to keep a straight count by updating siblings) and, of course, move:

TimestampModel

This trait adds created and updated datetime fields to your models, and valorizes them according to their names.

TogglableModel

This trait adds an active boolean field to your models, togglable via the toggle method and valorized upon insertion according to the getDefaultState method, which initially yields false but can be overridden in your model class:

Controllers

Routing

Controllers in Patchwork are plain Silex controllers, where you basically bind a callback to an URL/HTTP method couple. You can "mount" them to an URL endpoint in app/bootstrap.php:

Silex manual

FrontController

The FrontController class binds some basic routes to the app's root:

• /: renders the app/views/front/partials/home.twig template
• /robots.txt: renders a generic robots.txt file depending on the environment
• /admin: redirects the user to the route defined in the app/config/settings/common.yml file (at admin.root)

EntityController

The EntityController class describes a controller dedicated to managing a certain model (its constructor takes a table name as a parameter).

This class is abstract and extended by AdminController, that binds an HTTP authentication mechanism to itself and exposes CRUD GUI routes:

You can also inherit from it in your own controllers in order to customize its behaviour. To do so, you simply need to declare a connect method:

Finally, you can also create your own entity controllers by extending the abstract class itself (e.g. if you need a RSSController or something among these lines).

Third-party packages

Adding new packages to your application is as simple as running composer require [package] (eventually along with the --dev option, depending on whether the package will be used on production).

Front-end development

Workflow

When running gulp without a parameter, it runs a workflow task which processes your assets and launches a livereload server triggered by a file change in a template or config file, or directly in an asset (which also rebuilds it specifically).

Once you're done with coding, kill the livereload server and run gulp --dist to generate production-ready assets.

Stylesheets

You can either use LESS or plain CSS.

The recommended structure for your app/assets/less directory looks like this:

Main stylesheet

Check out app/assets/less/front/main.less to see how core stylesheets are used:

• It includes reset.less, which homogenizes styles across browsers.
• It includes a local variables.less file which extends the core's eponymous one (see below).
• It includes a local fonts.less file to define fonts (see below).
• It includes a local mixins.less file which extends the core's eponymous one (see below).

Variables

Here are the core-defined (and overrideable) variables:

You can thus write media queries like @media screen and @large-only, @retina.

Mixins

The following mixins are available:

JavaScript

You app/assets/js directory should contain a main.js file, which will be the entry point of your front-end code. It can make use of other files through the require method, as long as these files expose a module.exports property, according to the CommonJS module definition.

Everything will then be compiled into a single public/assets/js/main.js file by gulp.

You may use the provided domqueryall to get an array instead of a NodeList when querying the DOM for multiple elements:

Browserify manual

Images

Images are copied from app/assets/img to public/img by gulp, and minified when it is ran in production mode.

Fonts

TTF fonts are copied from app/assets/font to public/font and declined in EOT and WOFF formats by gulp.

Webfont handling is helped by Patchwork's LESS mixins:

Back-office

In the back-office, Patchwork relies on Twitter's Bootstrap for building CRUD interfaces. Check out app/views/admin/pizza for working samples.

Bootstrap manual

Third-party packages

Adding new packages to your application is as simple as running npm install [package] --save-dev. You will always use this option since production JS code will always consist of files of your own, where third-party code is compiled within, and will thus never deploy such code "as-is".

Extra gulp plugins may be installed as well, in order to enhance further the front-end build process by editing gulpfile.js.

gulp manual

Testing

Unit

PHPUnit classes are to be located in app/tests/unit and to wear the [App]\Tests namespace. You can then simply run phpunit at the application's root to play your tests.

PHPUnit's configuration is done through the phpunit.xml file.

PHPUnit manual

Functional

Behat features are to be located in app/tests/functional, and context classes go in bootstrap, which is a subdirectory of the latter. A sample context class is already provided and extends Neemzy\Patchwork\Tests\FeatureContext, which adds some vocabulary to Mink:

Tests are ran through BrowserKit, or PhantomJS when features are prefixed with @javascript.

Behat manual

Mink manual

Deployment

PHP dependencies

Run composer install --no-dev -o on your production server (or during your continuous integration build) to only retrieve the packages your application actually uses, and generate an optimized autoloader.

Assets

You are not supposed to compile your assets on your production server. It is not his role to worry about that. This is why, in its basic setup, Patchwork doesn't .gitignore the public/assets folder. You can then version production-ready (compiled and minified) assets to have them deployed instead (if you version-control compiled assets anyway, you may as well only commit these).

If you use continuous integration (better), you can safely .gitignore public/assets and have production-ready asset compilation be handled by your build.

Credits

Written by neemzy. You may check out the following PHP packages of mine, which are used in Patchwork:

• patchwork-core: Core files for Patchwork
• environ: Lightweight environment manager
• environ-service-provider: Environ service provider for Silex micro-framework
• redbean-service-provider: RedBean ORM service provider for Silex micro-framework
• share-extension: Twig extension providing social sharing links

Contributions and pull requests are very welcome :)