Skip to content

Commit 7858dad

Browse files
weaverryanweaverryan
committed
[book][installation] Adding a basic installation chapter
1 parent bbcb0f0 commit 7858dad

File tree

3 files changed

+161
-0
lines changed

3 files changed

+161
-0
lines changed

‎book/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ Book
66

77
http_fundamentals
88
from_flat_php_to_symfony2
9+
installation
910
page_creation
1011
doctrine/index
1112
controller

‎book/installation.rst

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
.. index::
2+
single: Installation
3+
4+
Installing and Configuring Symfony
5+
==================================
6+
7+
The goal of this chapter is to get you up-and-running with a working application
8+
built on top of Symfony. Fortunately, Symfony offers "distributions", which
9+
are functional Symfony "starter" projects that you can download and begin
10+
developing in immediately.
11+
12+
Downloading a Symfony2 Distribution
13+
-----------------------------------
14+
15+
Symfony2 packages "distributions", which are fully-functional applications
16+
that include the Symfony2 core libraries, a selection of useful bundles, a
17+
sensible directory structure and some default configuration. When you download
18+
a Symfony2 distribution, you're downloading a functional application skeleton
19+
that can be used immediately to begin developing your application.
20+
21+
Start by visiting the Symfony2 download page at `http://symfony.com/download`_.
22+
On this page, you'll see the *Symfony Standard Edition*, which is the main
23+
Symfony2 distribution. Here, you'll need to make two choices:
24+
25+
* Download either a ``.tgz`` or ``.zip`` archive - both are equivalent, download
26+
whatever you're more comfortable using;
27+
28+
* Download the distribution with or without vendors. If you have `Git`_ installed
29+
on your computer, you should download Symfony2 "without vendors", as it
30+
adds a bit more flexibility when including third-party/vendor libraries.
31+
32+
Download one of the archives somewhere under your local web server/s root
33+
directory and unpack it. From a UNIX command line, this can be done with
34+
one of the following commands (replacing ``###`` with your actual filename):
35+
36+
.. code-block:: bash
37+
38+
# for .tgz file
39+
tar zxvf Symfony_Standard_Vendors_2.0.###.tgz
40+
41+
# for a .zip file
42+
unzip Symfony_Standard_Vendors_2.0.###.tgz
43+
44+
When you're finished, you should have a ``Symfony/`` directory that looks
45+
something like this:
46+
47+
.. code-block:: text
48+
49+
www/ <- your web root directory
50+
Symfony/ <- the unpacked archive
51+
app/
52+
cache/
53+
config/
54+
logs/
55+
src/
56+
...
57+
vendor/
58+
...
59+
web/
60+
app.php
61+
...
62+
63+
Updating Vendors
64+
~~~~~~~~~~~~~~~~
65+
66+
Finally, if you downloaded the archive "without vendors", install the vendors
67+
by running the following command from the command line:
68+
69+
.. code-block:: bash
70+
71+
php bin/vendors.php
72+
73+
.. tip::
74+
75+
You can call ``php bin/vendors.php --min`` if you don't want all of the
76+
Git history for your vendor libraries. This also makes the installation
77+
much faster.
78+
79+
This command downloads all of the necessary vendor libraries - including Symfony
80+
itself - into the ``vendor/`` directory.
81+
82+
Configuration and Setup
83+
~~~~~~~~~~~~~~~~~~~~~~~
84+
85+
At this point, all of the needed third-party libraries now live in the ``vendor/``
86+
directory. You also have a default application setup in ``app/`` and some
87+
sample code inside the ``src/`` directory.
88+
89+
Symfony2 comes with a visual server configuration tester to help make sure
90+
your Web server and PHP are configured to use Symfony. Use the following URL
91+
URL to check your configuration:
92+
93+
.. code-block:: text
94+
95+
http://localhost/Symfony/web/config.php
96+
97+
If there are any issues, correct them now before moving on.
98+
99+
.. sidebar:: Setting up Permissions
100+
101+
One common issue is that the ``app/cache`` and ``app/log`` directories
102+
must be writable both by the web server and the command line user. On
103+
a UNIX system, if your web server user is different from your command
104+
line user, you can run the following commands just once in your project
105+
to ensure that permissions will be setup properly. Change ``www-data``
106+
to the web server user and ``yourname`` to your command line user:
107+
108+
.. code-block:: bash
109+
110+
rm -rf app/cache/*
111+
rm -rf app/log/*
112+
113+
sudo chmod +a "www-data allow delete,write,append,file_inherit,directory_inherit" app/cache
114+
sudo chmod +a "www-data allow delete,write,append,file_inherit,directory_inherit" app/logs
115+
116+
sudo chmod +a "yourname allow delete,write,append,file_inherit,directory_inherit" app/cache
117+
sudo chmod +a "yourname allow delete,write,append,file_inherit,directory_inherit" app/logs
118+
119+
When everything is fine, click on "Go to the Welcome page" to request your
120+
first "real" Symfony2 webpage:
121+
122+
.. code-block:: text
123+
124+
http://localhost/Symfony/web/app_dev.php/
125+
126+
Symfony2 should welcome and congratulate you for your hard work so far!
127+
128+
.. image:: /images/quick_tour/welcome.jpg
129+
130+
Beginning Development
131+
---------------------
132+
133+
Now that you have a fully-functional Symfony2 application, you can begin
134+
development! Your distribution may contain some sample code - check the
135+
``README.rst`` file included with the distribution (open it as a text file)
136+
to learn about what sample code was included with your distribution and how
137+
you can remove it later.
138+
139+
Using Source Control
140+
~~~~~~~~~~~~~~~~~~~~
141+
142+
If you're using a version control system like ``Git`` or ``Subversion``, you
143+
can begin committing your project as normal. If you've downloaded the archive
144+
*without vendors*, you can safely ignore the entire ``vendors/`` directory
145+
and not commit it to source control. With ``Git``, this is done by creating
146+
and adding the following to a ``.gitignore`` file:
147+
148+
.. code-block:: text
149+
150+
vendor/
151+
152+
Now, the vendor directory won't be committed to source control. This is fine
153+
(actually, it's great!) because when someone else clones our checks out the
154+
project, he/she can simply run the ``php bin/vendors.php`` script to download
155+
all the necessary vendor libraries.
156+
157+
.. _`http://symfony.com/download`: http://symfony.com/download
158+
.. _`Git`: http://git-scm.com/

‎book/map.rst.inc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
* :doc:`Symfony2 Fundamentals </book/http_fundamentals>`
22
* :doc:`When flat PHP meets Symfony </book/from_flat_php_to_symfony2>`
3+
4+
* :doc:`Installing and Configuring Symfony </book/installation>`
35
* :doc:`The Basics of Page Creation </book/page_creation>`
46

57
* :doc:`Controllers </book/controller>`

0 commit comments

Comments
 (0)