README

The "Symfony Standard" distribution in the LIN3S way.

Why?

Symfony is a set of reusable PHP components and a PHP framework for web projects. In LIN3S we implement this solution providing some useful features that the standard edition of Symfony doesn't come with:

Dependencies not included in this file.

Capistrano deploy
A complete base.html.twig based on HTML5 Boilerplate
As dev dependency, Doctrine Fixtures
Coding standards library made by LIN3S

Prerequisites

The above sounds great so, now, to start developing with our Symfony Standard, you need to meet the following requirements:

PHP 5.4 or higher
MySQL or [MongoDB][178]
Composer: curl -sS https://getcomposer.org/installer | php
Ruby

Bundler: gem install bundler
After bundler: bundle install (see Gemfile)

Node.js 4.0 or higher

Gulp.js: npm install -g gulp
ESLint: npm install -g eslint

Getting Started

After installing all the prerequisites, to create a Symfony project based on this Symfony Standard, you should follow these steps.

Firstly, you need to create the project:

$ composer create-project lin3s/symfony-standard <project-name> && cd <project-name>

If your app/config/parameters.yml file was not created right after finishing the composer process, the system will ask you some questions in order to create the needed file. If you want to create it by hand, just copy the app/config/parameters.yml.dist file: $ cp app/config/parameters.yml.dist app/config/parameters.yml

If the process fails as soon as it finishes, it's because the database is not created yet. Run php app/console doctrine:database:create in order to create it and then create the needed tables with php app/console doctrine:migrations:migrate command.

After that, if you use a Web server, you should visit the Symfony permissions section of the installation documentation so your CLI user and Web server user are allowed to write cache, logs and sessions* folders. You may use these commands:

$ rm -rf app/cache/*
$ rm -rf app/logs/*
$ rm -rf app/sessions/*

$ HTTPDUSER=`ps axo user,comm | grep -E '[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx' | grep -v root | head -1 | cut -d\  -f1`
$ sudo chmod +a "$HTTPDUSER allow delete,write,append,file_inherit,directory_inherit" app/cache app/logs app/sessions
$ sudo chmod +a "`whoami` allow delete,write,append,file_inherit,directory_inherit" app/cache app/logs app/sessions

Also, if you are using Apache Web server, consider renaming .htaccess.dist files located within the app, src and web folders to .htaccess or create the proper server configuration to improve global performances.

If you are willing to use LiipImagineBundle, create the needed folder:

$ mkdir -p web/media/cache

You can modify this path editing the cache parameter in the liip_imagine section within the app/config/config.yml file. Also remember to give this folder the right permissions so the web server is allowed to write.

If you want to load some default users, run the following command in order to create an admin/admin account and 50 fake users:

$ php app/console doctrine:fixtures:load

Also, if you want to create an admin user by hand, follow these steps:

$ php app/console fos:user:create
$ php app/console fos:user:promote --> give the ROLE_SUPER_ADMIN permission

In order to use the built-in server, use the following command:

$ php app/console server:run

Access to your admin panel by going to <domain>/admin

A complete app/Resources/views/base.html.twig file is provided by default. Be sure to modify this file and override the meta blocks whenever it's needed. Commented out you can find usefull examples with the full information links and validators.

We improved the production logs managed by monolog. Edit app/config/config_prod.yml so it suits your needs.

If you are planning to add some tests, be sure to edit your composer.json autoload section with something like this:

"autoload": {
    "psr-4": { "": "src/" },
    "classmap": [ "app/AppKernel.php", "app/AppCache.php" ],
    "exclude-from-classmap": [ "/Tests/", "/test/", "/tests/" ]
},

Also, if your development IDE is PhpStorm, uncomment the following line in app/config/config.yml:

framework:
    ide: "phpstorm://open?file=%%f&line=%%l"

Front-end workflow

First of all, download all the dependencies needed for Ruby and Node.js:

$ bundle install
$ npm install

Feel free to add and/or edit the npm dependencies by editing the package.json file.

After this initial step, you will have the following gulp tasks available:

gulp sass: compiles app/Resources/assets/scss/app.scss and moves the resulting file to web/ folder.
gulp sass:prod: compiles and minifies app/Resources/assets/scss/app.scss and moves the resulting file to web/ folder.
gulp scss-lint: it helps you to keep your SCSS files clean and readable.
gulp modernizr: creates a modernizr.js file with the selected tests.
gulp js: copies the JS files to the web/js folder to work in the dev environment.
gulp js:prod: combines and minifies the needed JS files, including modernizr.js.
gulp sprites: creates a SVG sprite.
gulp watch: checks SCSS, JS and SVG changes to launch the corresponding task.
gulp default: executes sass, js:prod, sprites and starts watching.
gulp prod: executes sass:prod, modernizr, js:prod and spritest tasks.

As you see, you should create and/or edit .scss files within the app/Resources/assets/scss/ folder. An initial structure is already given for you. You can also add/or edit .js files, but remember to modify gulpfile.js jsFiles variable in order to add what your project needs, adding the new files to base.html.twig too.

Also, livereload is up and running when launching gulp watch. You should install the correct browser extension and be sure to navigate through the dev environment.

Doctrine Extensions

This bundle is installed by default. You just have to enable what your project needs, for example:

stof_doctrine_extensions:
    orm:
        default:
            sluggable: true
            timestampable: true

Some extensions do need an extra configuration in the doctrine section of the app/config/config.yml file. Check the full configuration here.

For the other possible configurations, visit the bundle documentation

Doctrine Migrations

Capistrano will run the needed migrations when running a deployment. You just need to generate the correct files within the app/migrations folder. In order to do so, just run php app/console doctrine:migrations:diff and push the generated file to your SCM before runnning the deploy.

For other possible configurations, visit the bundle documentation

Deployment

To automatize the deployment process this project is using Capistrano with capistrano-symfony plugin. You can find the whole configuration within the deploy directory. Customize deploy tasks modifying the deploy/deploy.rb file.

You should update the symfony-standard application name for your awesome project name and the repo url with your Git project url.

Inside deploy/stages directory there are two files that can be considered as pre-production stage and production stage. There is no logic, these files only contain few parameters that you should customize for your proper deployment.

After all, and following the Capistrano documentation to configure the server, you can deploy executing:

$ cap <stage> deploy    # <stage> can be dev1, prod or whatever file inside stages directory

In the Capistrano shared directory you should create the app/config/parameters.yml file, app/logs, app/sessions and web/uploads folder should be created for you.

###Clearing remote caches

When working with PHP7 & Opcache, for example, you won't see all changes after deploying. Caches need to be flushed with the correct website domain. If you need this feature, just open the deploy.rb file and remove the commented line:

  #after :finishing, 'cache:clear'

This is done by Smart-Core/AcceleratorCacheBundle. If you need different configurations for your deployment stages, feel free to create a variable and add the required parameters to the stages/*.rb files.

lin3s / symfony-standard

Maintainers

Details