Skip to content

Updated installation instructions to use the new Symfony Installer #4580

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Dec 20, 2014
Merged

Updated installation instructions to use the new Symfony Installer #4580

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b69a5cd
Updated installation instructions to use the new Symfony Installer
javiereguiluz Dec 3, 2014
4b8e805
Restored the original section title
javiereguiluz Dec 12, 2014
f58db71
Fixed section headers
javiereguiluz Dec 14, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 29 additions & 85 deletions best_practices/creating-the-project.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,50 +4,39 @@ Creating the Project
Installing Symfony
------------------

There is only one recommended way to install Symfony:
In the past, Symfony projects were created with `Composer`_, the dependency manager
for PHP applications. However, the current recommendation is to use the **Symfony
Installer**, which has to be installed before creating your first project.

.. best-practice::

Always use `Composer`_ to install Symfony.

Composer is the dependency manager used by modern PHP applications. Adding or
removing requirements for your project and updating the third-party libraries
used by your code is a breeze thanks to Composer.

Dependency Management with Composer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Linux and Mac OS X Systems
~~~~~~~~~~~~~~~~~~~~~~~~~~

Before installing Symfony, you need to make sure that you have Composer installed
globally. Open your terminal (also called *command console*) and run the following
command:
Open your command console and execute the following:

.. code-block:: bash

$ composer --version
Composer version 1e27ff5e22df81e3cd0cd36e5fdd4a3c5a031f4a 2014-08-11 15:46:48
$ curl -LsS http://symfony.com/installer > symfony.phar
$ sudo mv symfony.phar /usr/local/bin/symfony
$ chmod a+x /usr/local/bin/symfony

You'll probably see a different version identifier. Never mind because Composer
is updated on a continuous basis and its specific version doesn't matter.
Now you can execute the Symfony Installer as a global system command called
``symfony``.

Installing Composer Globally
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Windows Systems
~~~~~~~~~~~~~~~

In case you don't have Composer installed globally, execute the following two
commands if you use Linux or Mac OS X (the second command will ask for your
user password):
Open your command console and execute the following:

.. code-block:: bash

$ curl -sS https://getcomposer.org/installer | php
$ sudo mv composer.phar /usr/local/bin/composer
c:\> php -r "readfile('http://symfony.com/installer');" > symfony.phar

.. note::
Then, move the downloaded ``symfony.phar`` file to your projects directory and
execute it as follows:

Depending on your Linux distribution, you may need to execute ``su`` command
instead of ``sudo``.
.. code-block:: bash

If you use a Windows system, download the executable installer from the
`Composer download page`_ and follow the steps to install it.
c:\> php symfony.phar

Creating the Blog Application
-----------------------------
Expand All @@ -58,64 +47,19 @@ to create files and execute the following commands:

.. code-block:: bash

# Linux, Mac OS X
$ cd projects/
$ composer create-project symfony/framework-standard-edition blog/

This command will create a new directory called ``blog`` that will contain
a fresh new project based on the most recent stable Symfony version available.

Checking the Symfony Installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Once the installation is finished, enter the ``blog/`` directory and check that
Symfony is correctly installed by executing the following command:

.. code-block:: bash

$ cd blog/
$ php app/console --version

Symfony version 2.6.* - app/dev/debug

If you see the installed Symfony version, everything worked as expected. If not,
you can execute the following *script* to check what does prevent your system
from correctly executing Symfony applications:

.. code-block:: bash

$ php app/check.php

Depending on your system, you can see up to two different lists when executing the
`check.php` script. The first one shows the mandatory requirements which your
system must meet to execute Symfony applications. The second list shows the
optional requirements suggested for an optimal execution of Symfony applications:

.. code-block:: bash

Symfony2 Requirements Checker
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

> PHP is using the following php.ini file:
/usr/local/zend/etc/php.ini

> Checking Symfony requirements:
.....E.........................W.....

[ERROR]
Your system is not ready to run Symfony2 projects

Fix the following mandatory requirements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* date.timezone setting must be set
> Set the "date.timezone" setting in php.ini* (like Europe/Paris).

Optional recommendations to improve your setup
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$ symfony new blog

* short_open_tag should be disabled in php.ini
> Set short_open_tag to off in php.ini*.
# Windows
c:\> cd projects/
c:\projects\> php symfony.phar new blog
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what do you think of making tabs for this? bash-unix, bash-windows?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the idea, but we don't have resources to do it now. I prefer to merge this PR as soon as possible and then improve things like this.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All we would have to do is to add labels for the new tabs to the conf.py file which you would need to deploy on the build server. Is that still a hard task to do?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still remember the "varnish tabs" nightmare and the "best practice tab" horror story. I'm afraid that I'm too old to still believe that anything related to software is easy or it will work at first.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see your point. You know the build process better than I do.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@javiereguiluz couldn't the build process import the conf.py available in the doc repo and then overwrite only the settings it needs to change ? This would avoid you to change the build config for such changes done by the doc team to add new syntax highlightings for instance

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@stof what we're really going to do is to remove from the best practices book all the explanations regarding how to install Symfony and create the application. Soon we'll change the current "Use Composer to install Symfony" practice for "Use the Symfony Installer to create Symfony apps". We won't explain anything else because the book explains all in detail.

But while we change that, this PR is a quick fix to the problem of not explaining correctly how to install Symfony. That's why I'd love to see it merged soon :)


This command creates a new directory called ``blog`` that contains a fresh new
project based on the most recent stable Symfony version available. In addition,
the installer checks if your system meets the technical requirements to execute
Symfony applications. If not, you'll see the list of changes needed to meet those
requirements.

.. tip::

Expand Down