Symfony
Installation
1. Install the Symfony installer
sudo mkdir -p /usr/local/bin
sudo curl -LsS https://symfony.com/installer -o /usr/local/bin/symfony
sudo chmod a+x /usr/local/bin/symfony
2. Create your local working copy
Go to your websites directory and use the symfony command to initialize your project:
cd /path/to/your/www_directory
symfony new website.dev
The symfony command will initialize a fresh new Symfony 3 project and install the basic dependencies.
3. Git setup
Then, you can Initialize your working copy and remote repository:
cd /path/to/your/www_directory/website.dev
git init
git remote add origin [email protected]:leapt/website.git
4. Check the result in your browser
You can then edit your host file in order to be able to access the website. On Mac OS, you can open the terminal and type:
sudo nano /etc/hosts
Add the following lines to the host file:
127.0.0.1 website.dev
You can also add a website config in nginx:
server {
listen 80;
server_name website.test;
root /var/www/website.test/public;
location /tests/ {
alias /var/www/website.test/tests/_html/;
index index.html;
fastcgi_index index.html;
}
error_page 503 @maintenance;
location @maintenance {
rewrite ^(.*)$ /maintenance.html break;
}
location / {
if (-f /var/www/website.test/public/maintenance.html) {
return 503;
}
try_files $uri /index.php$is_args$args;
}
location ~ ^/index.php(/|$) {
fastcgi_pass unix:/run/php/php7.4-fpm.sock;
fastcgi_split_path_info ^(.+.php)(/.*)$;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
fastcgi_param DOCUMENT_ROOT $realpath_root;
internal;
}
location ~ .php$ {
return 404;
}
proxy_buffer_size 512k;
proxy_buffers 4 512k;
proxy_busy_buffers_size 512k;
client_max_body_size 20M;
error_log /var/log/nginx/website.test_error.log;
access_log /var/log/nginx/website.test_access.log;
}
Normally, you can then access the newly created bundle in your browser: http://website.dev/
5. Commit and push
Assuming you are still in your project directory:
git add .
git commit -m "Project setup"
git push origin master
Getting a working copy
1. Clone the project
cd ~/Sites
git clone [email protected]:leapt/website.git website.dev
2. Install vendors
Log in into your vagrant instance, and load vendors by
cd /var/www/website.dev
composer install
3. Assets
bin/console assets:install --symlink web
# Not necessarily needed
npm install
bower install
4. Database setup
# Create the database
bin/console doctrine:database:create
# If your project runs under Doctrine migrations, you can launch
bin/console doctrine:migrations:migrate
# Otherwise, update the schema by introspection
bin/console doctrine:schema:update --force
# And if the project has fixtures
bin/console doctrine:fixtures:load
5. Check the result in your browser
You can then edit your host file in order to be able to access the website. On Mac OS/Linux, you can open the terminal and type:
sudo sh -c "echo '127.0.0.1 website.dev\n::1 website.dev' >> /etc/hosts"
You can also add a website config in nginx:
server {
listen 80;
server_name website.test;
root /var/www/website.test/public;
location /tests/ {
alias /var/www/website.test/tests/_html/;
index index.html;
fastcgi_index index.html;
}
error_page 503 @maintenance;
location @maintenance {
rewrite ^(.*)$ /maintenance.html break;
}
location / {
if (-f /var/www/website.test/public/maintenance.html) {
return 503;
}
try_files $uri /index.php$is_args$args;
}
location ~ ^/index.php(/|$) {
fastcgi_pass unix:/run/php/php7.4-fpm.sock;
fastcgi_split_path_info ^(.+.php)(/.*)$;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
fastcgi_param DOCUMENT_ROOT $realpath_root;
internal;
}
location ~ .php$ {
return 404;
}
proxy_buffer_size 512k;
proxy_buffers 4 512k;
proxy_busy_buffers_size 512k;
client_max_body_size 20M;
error_log /var/log/nginx/website.test_error.log;
access_log /var/log/nginx/website.test_access.log;
}
Normally, you can then access the newly created bundle in your browser: http://website.dev/
Basic bundle development
This section explains the basics of how to work with Models, Views & Controllers in Symfony 3.
The goal here is not to take the place of the official Symfony documentation, but rather
- to help you put the pieces together
- to document the coding standard and practices
Before you dive into the next sections, please make sure you have read and understood the two following articles in the official Symfony2 documentation:
1. Creation of a base layout template
If you are not already familiar with Twig, go ahead and read the following resources:
Your first step will be to create a base layout template. You can create it in the app/Resources/views directory. Our convention is to call it base.html.twig.
Here is a sample base.html.twig template, with the blocks you will need to create:
<!DOCTYPE html>
<html>
<head>
<title>Page title</title>
<meta charset="UTF-8">
{% if app.environment == 'dev' %}
<link rel="stylesheet" type="text/css" href="{{ asset('build/styles/main.css') }}" media="all">
<link rel="stylesheet" type="text/css" href="{{ asset('build/styles/vendor.css') }}" media="all">
{% else %}
<link rel="stylesheet" type="text/css" href="{{ asset('build/styles/main.min.css') }}" media="all">
<link rel="stylesheet" type="text/css" href="{{ asset('build/styles/vendor.min.css') }}" media="all">
{% endif %}
<link rel="icon" type="image/x-icon" href="{{ asset('build/images/favicon.ico') }}">
</head>
<body>
{% block body %}{% endblock body %}
{% if app.environment == 'dev' %}
<script src="{{ asset('build/scripts/vendor.js') }}"></script>
<script src="{{ asset('build/scripts/main.js') }}"></script>
{% else %}
<script src="{{ asset('build/scripts/vendor.min.js') }}"></script>
<script src="{{ asset('build/scripts/main.min.js') }}"></script>
{% endif %}
</body>
</html>
2. Assets setup
As you can see in the example above, asset files (js and css) are located in a "public" directory in your app Resources folder. You will need to create that directory yourself.
We use the following structure:
-
Resources
-
public
- fonts
- images
- less
- js
- vendor
-
public
If you need to call some javascript libraries and they can't be managed using bower/gulp, download them in the vendor directory. But keep their directory structure if it's the case.
For example:
-
vendor (folder)
- bootstrap (folder)
- jquery.js
- modernizr.js
- respond.js
Please avoid using Assetic and prefer gulp instead.
3. Controller and templates
Now, you can start the generated controller by the installation of Symfony. Usually, the first step is to have an index action in the default controller, without any parameter, to serve as the starting point of the website or application.
You can achieve that result by modifying the indexAction method and the associated @Route
annotation:
/**
* @Route("")
* @Template()
*/
public function indexAction($name)
{
return [];
}
You will find more information about how to use route and controllers in the following articles:
Note : The controller renders the AppBundle:default:index.html.twig template, which uses the following naming convention:
bundle_name:controller_name:template_name
This is the logical name of the template, which is mapped to a physical location using the following convention:
app/Resources/views/controller_name/template_name
Now, you probably would extend the base.html.twig template into child templates. The extends tag should be the first tag in the template. Simply add this line into your child template:
{% extends "::base.html.twig" %}
If you want to print a block multiple times you can however use the block function. Define some blocks in your base.html.twig template:
{% block title %}
{% block body %}
{% block stylesheets %}
{% block javascripts %}
You will find more information about how to use the block function: Twig blocks
4. Coding standards
PSR-0 is a standard that has been adopted by some frameworks like Zend Framework 2 to facilitate the autoloading process across platforms. This is accomplished by following namespace and class naming standards that correspond to the relative location of the resource or file in question.
If you are not already familiar with PHP Specification Request, go ahead and read the following resource: PSR-0
CamelCase for Symfony entity:
When contributing code to Symfony, you must follow its coding standards. Symfony follows the standards defined in the PSR-0, PSR-1 and PSR-2 documents.
In short :
- Use camelCase, not underscores, for variable, function and method names, arguments;
- Use underscores for option names and parameter names;
- Use namespaces for all classes;
- Prefix abstract classes with Abstract. Please note some early Symfony classes do not follow this convention and have not been renamed for backward compatibility reasons. However all new abstract classes must follow this naming convention;
- Suffix interfaces with Interface;
- Suffix traits with Trait;
- Suffix exceptions with Exception;
- Use alphanumeric characters and underscores for file names;
- Don't forget to look at the more verbose Conventions document for more subjective naming considerations.
If you need more documentation, read those articles below:
Twig coding standards
Twig is the default template engine of Symfony. Twig uses a syntax similar to the Django and Jinja template languages which inspired the Twig runtime environment.
Filters, variables and functions names are in lowercase and can be more readable by using underscore to separate parts of their name.
Example:
{% set foo_bar = 'foo' %}
{{ a_variable }}
{{ 'some example text'|custom_filter(some_parameters) }}
{{ render_my_function(some_parameters) }}
If you want to learn more about how to use Twig synthax and semantic, please visit those pages:
Translations
This section explains the basics of how to use translations in Symfony.
1. Install i18n Bundle
composer require leapt/im-bundle:~1.0
2. Register bundle in AppKernel
# in app/AppKernel.php:
public function registerBundles()
{
$bundles = [
...
new Leapt\I18nBundle\LeaptI18nBundle(),
];
3. Change site routing and add available languages
Change type of site's routing in annotation_i18n
:
# in app/config/routing.yml
yourname_site:
type: annotation_i18n
Add all languages needed. See example below:
# in app/config/config.yml
leapt_i18n:
locales: ["fr", "nl", "en"]
4. Enabling the translation Twig filter
Remove the comment tag '#' before the translator filter on line 7:
# in app/config/config.yml
framework
translator: { fallback: %locale% }
5. Enable i18nRoute in a Controller
See example below:
use Leapt\I18nBundle\Annotation\I18nRoute;
class DefaultController
{
/**
* @I18nRoute("/", name="app_default_index")
*/
public function indexAction()
{
6. Create translation files
In src/AppBundle/Resources/ create the 'translations' directory For each language, create a messages.'thechosenlanguage'.yml
Now you can structure the yml file as you will. Keep in mind to make it simple, don't use to many sub-levels. We recommend you to use only 3 levels.
For example:
sitename: Your site name
meta:
home:
title: Home
default:
title: Your campaign name
description: ...
In your twig template, simply call the translated message this way:
{{ 'meta.home.title'|trans }}