What is the new Symfony 3 directory structure?
I want to use the new Symfony 3 directory structure, but I don't see the question?
The question Would you like to use Symfony 3 directory structure?
has been removed when creating a new project due to the confusion it caused. You can force the use of the directory structure using the following:
If you prefer the new structure, you can add the environment variable SENSIOLABS_ENABLE_NEW_DIRECTORY_STRUCTURE
to your .bashrc
or .bash_profile
like so:
Make all future projects ask for the new structure
# .bash_profile
# ALL new composer installs will ask `Would you like to use the new Symfony3 strucure?`
export SENSIOLABS_ENABLE_NEW_DIRECTORY_STRUCTURE=true
Make ONLY THIS project ask if we want to use the new structure.
If you wanted it for a particular project only (a one off), you can use:
SENSIOLABS_ENABLE_NEW_DIRECTORY_STRUCTURE=true composer create-project symfony/framework-standard-edition path/ "2.5.*"
If the environment variable SENSIOLABS_ENABLE_NEW_DIRECTORY_STRUCTURE
is set and set to true
, composer
will ask if you want to use the new directory structure.
Continue reading below for all the changes between the Symfony2
and Symfony3
directory structure.
What is the new Symfony 3 directory structure?
(and how does it effect me & my workflow)
I looked into this by creating 2 projects, one with symfony-2.5.0
directory structure, one with symfony-3
(directory structure change only).
Make one of each project:
# say `N` to `Would you like to use Symfony 3 directory structure?`
$ composer create-project symfony/framework-standard-edition symfony-2.5.0/ 2.5.0
# say `Y` to `Would you like to use Symfony 3 directory structure?`
$ composer create-project symfony/framework-standard-edition symfony-3/ 2.5.0
So now we have the 2 different directories we want to compare.
Find the diff
erence
You can diff
between the 2 directories using:
$ diff -rq symfony-2.5.0/ symfony-3/
/** (Returned from the diff)
Files symfony-2.5.0/.gitignore and symfony-3/.gitignore differ
Files symfony-2.5.0/.travis.yml and symfony-3/.travis.yml differ
Only in symfony-2.5.0/app: bootstrap.php.cache
Only in symfony-2.5.0/app: cache
Only in symfony-2.5.0/app: console
Only in symfony-2.5.0/app: logs
Only in symfony-2.5.0/app: phpunit.xml.dist
Only in symfony-3/bin: console
Only in symfony-3/bin: symfony_requirements
Files symfony-2.5.0/composer.json and symfony-3/composer.json differ
Only in symfony-3/: phpunit.xml.dist
Only in symfony-3/: var
Files symfony-2.5.0/vendor/autoload.php and symfony-3/vendor/autoload.php differ
Files symfony-2.5.0/vendor/composer/autoload_real.php and symfony-3/vendor/composer/autoload_real.php differ
Files symfony-2.5.0/web/app.php and symfony-3/web/app.php differ
Files symfony-2.5.0/web/app_dev.php and symfony-3/web/app_dev.php differ
*/
This shows the files that differ in the 2 versions.
Breakdown of diff
Here's a breakdown of everything in the diff.
# These files still exist in both versions (with different content)
.gitignore
.travis.yml
composer.json
vendor/autoload.php
vendor/composer/autoload_real.php
web/app.php
web/app_dev.php
# The following files have been removed from 2.5.0
# {RemovedFile2.5} | {ReplacedWith3.0}
app/cache | var/cache
app/logs | var/log
app/bootstrap.php.cache | var/bootstrap.php.cache
app/console | bin/console
app/phpunit.xml.dist | phpunit.xml.dist
# The following files are new in 3.0
bin/symfony_requirements # run via CLI
Benefits of the Symfony 3 directory structure
The new directory structure has a number of benefits, all of which are minor and may require minimal changes to your workflow.
PHPUnit
phpunit
can be run from the project root without having to explicitly specify the path of the configuration file.
# Symfony2
phpunit -c app/phpunit.xml
# Symfony3 (no need to specify the configuration file location)
phpunit
Binary Executables
All binary executable files are now all located in a single location - the bin
directory (similar to a unix-like os).
# you can update your `PATH` to include the `bin` directory
PATH="./bin:$PATH"
# From your project root you can now run executables like so:
console
symfony_requirements
doctrine
# else with no `PATH` update
bin/console
bin/symfony_requirements
bin/doctrine
The new /var
directory
The new /var
directory contains the files to which the system writes data to during the course of its operation (similar to a unix-like os).
This also makes it easier to add permissions, the entire /var
directory should be writable by your webserver. You can follow the Symfony2 guide for setting permissions (substituting app/cache
&& app/logs
with var
), any other files you want to write locally could also be located here.
# default symfony3 `var` directory
var/bootstrap.php.cache
var/cache
var/logs
Symfony requirements check
Running symfony_requirements
will output mandatory & optional environment configurations.
e.g:
********************************
* 'Symfony requirements check' *
********************************
* Configuration file used by PHP: /usr/local/php5/lib/php.ini
/** ATTENTION **
* The PHP CLI can use a different php.ini file
* than the one used with your web server.
* To be on the safe side, please also launch the requirements check
* from your web server using the web/config.php script.
*/
** Mandatory requirements **
'
OK PHP version must be at least 5.3.3 (5.5.11 installed)
OK PHP version must not be 5.3.16 as Symfony wont work properly with it
OK Vendor libraries must be installed
OK var/cache/ directory must be writable
OK var/logs/ directory must be writable
OK date.timezone setting must be set
OK Configured default timezone "Europe/London" must be supported by your installation of PHP
OK json_encode() must be available
OK session_start() must be available
OK ctype_alpha() must be available
OK token_get_all() must be available
OK simplexml_import_dom() must be available
OK APC version must be at least 3.1.13 when using PHP 5.4
OK detect_unicode must be disabled in php.ini
OK xdebug.show_exception_trace must be disabled in php.ini
OK xdebug.scream must be disabled in php.ini
OK PCRE extension must be available
'
** Optional recommendations **
'
OK xdebug.max_nesting_level should be above 100 in php.ini
OK Requirements file should be up-to-date
OK You should use at least PHP 5.3.4 due to PHP bug #52083 in earlier versions
OK When using annotations you should have at least PHP 5.3.8 due to PHP bug #55156
OK You should not use PHP 5.4.0 due to the PHP bug #61453
OK When using the logout handler from the Symfony Security Component, you should have at least PHP 5.4.11 due to PHP bug #63379 (as a workaround, you can also set invalidate_session to false in the security logout handler configuration)
OK You should use PHP 5.3.18+ or PHP 5.4.8+ to always get nice error messages for fatal errors in the development environment due to PHP bug #61767/#60909
OK PCRE extension should be at least version 8.0 (8.34 installed)
OK PHP-XML module should be installed
OK mb_strlen() should be available
OK iconv() should be available
OK utf8_decode() should be available
OK posix_isatty() should be available
OK intl extension should be available
OK intl extension should be correctly configured
OK intl ICU version should be at least 4+
OK a PHP accelerator should be installed
OK short_open_tag should be disabled in php.ini
OK magic_quotes_gpc should be disabled in php.ini
OK register_globals should be disabled in php.ini
OK session.auto_start should be disabled in php.ini
OK PDO should be installed
OK PDO should have some drivers installed (currently available: mysql, sqlite, dblib, pgsql)
'
Conclusion
Looks like a good tidy up by Sensio Labs, all the above changes make perfect sense, they should be easy to implement when upgrading from 2.5
to 3.x
, these will probably be the least of your problems!
Read the docs
Symfony 2.x => 3.0 Upgrade docs here
Symfony 3.0 The Architecture
Release Date for Symfony 3
It looks far off looking at the Release process (worth a read):
http://symfony.com/doc/current/contributing/community/releases.html
(source: symfony.com)
Here is a list of changes between the old and new directory structure:
- A new
var
folder is introduced app/console
is moved tobin/console
app/check.php
is moved/renamed tobin/symfony_requirements
app/phpunit.xml.dist
is moved to the root folderapp/SymfonyRequirements.php
is moved tovar/SymfonyRequirements.php
- the
app/cache
andapp/logs
folders have been moved tovar/cache
andvar/logs
, respectively
(Currently not all of the old files seem to be removed, so you might want to do so manually before committing all files into version control. See this issue)
So what's the benefit?
There are a couple of benefits with these changes. First of all, all files and folders that should be writable for Symfony are now in the var
folder. This should make configuring permissions a lot easier: simply assure write access to the var
folder and you're done.
This is suggested in this blog post - I haven't tried this myself, yet.
Secondly, all executables, including console
, are now in the bin
folder. That allows Bash users for instance to add this to their .profile
file:
# set PATH so it includes current bin folder
PATH="./bin:$PATH"
Now you don't even have to type bin/console
anymore, simply console
will suffice (note that I had to reboot in order for this to work).
There are some other improvements as well. app/check.php
is now an executable, so you can call it using bin/symfony_requirements
instead of php app/check.php
. (Using the .profile
trick I described earlier, simply symfony_requirements
will suffice as well)
And, last but not least, you no longer have to specify the location of the configuration file when running PHPUnit. So instead of phpunit -c app
you can simply execute phpunit
.
Can I upgrade existing projects to this new structure as well?
By default, you'll only get the 'Do you want to use the new directory structure' question when creating a new project (using composer create-project symfony/framework-standard-edition path/ "2.5.*"
).
However, it is possible to upgrade an existing Symfony application, but it's a somewhat hacky solution. I have managed to do so with a number of applications now, and you can read the steps in this gist. However, since it wasn't designed for this, I can not guarantee it will allways work.
Update
It turns out that Symfony no longer asks you if you want to use the new directory structure, when creating a new Symfony application through Composer. However, it is still possible to create Symfony projects with the new directory structure, by using an environment variable. For more information, see How can I create a new Symfony project with the new directory structure?