How to Setup Docker for Your Symfony Project

As you probably know, I am a big Symfony fan :) In the last few years I used Vagrant to set up my Symfony development environment more or less as described here. But we now have Docker and it’s time to move forward with a new setup. Docker containers are generally more lightweight than Vagrant virtual machines, so starting and stopping them is extremely fast. They also take a lot less disk space.

For this post I got some inspiration from here but extended it to have an additional MySQL database container.

To setup a Docker container you need a Dockerfile file and to combine several containers we use the docker-compose.yml file. For our environment we will need two containers, one with the latest Ubuntu LTS to host the web server and our project files and one for MySQL.

The first container is defined in the Dockerfile file as below:

[crayon-5b76d23287bea625108635/]

Add this file in a new folder. We also need the vhost.conf and run.sh files used in the code from above.

The vhost.conf file is used to configure the apache virtual host:

[crayon-5b76d23287c01482497499/]

The run.sh file runs when the container starts and just makes sure that the cache and logs folders are set up before launching the apache web server:

[crayon-5b76d23287c1a301460394/]

That’s all for our main Ubuntu container, we now need to create the docker-compose.yml file:

[crayon-5b76d23287c29066747513/]

This will tell Docker to first start an MySQL 5.7 container, then our Ubuntu container that will be able to access the MySQL container using the mysql host name.

Start everything with the docker-compose up command.

When it’s done, open a new terminal (let the latest docker compose command run, do not stop it) and use the docker ps command to see the running containers:

Now, you can take the id of the Ubuntu container and ssh into it:

[crayon-5b76d23287c35197008819/]

Here you will start a new Symfony project as always (you will have to delete the my_project folder created by Docker first):

[crayon-5b76d23287c3e749112954/]

If you name you project something else (yes, you will probably do that) just replace the all my_folder occurrences in the files and commands above with the actual name of your project.

After you created the new Symfony project, it is better to rebuild the Docker containers so the setup of the cache and logs folders will be as intended. In the terminal window where you launched Docker, press Ctrl+C to stop it then run docker-compose up again.

That’s it! You can now access your new Symfony project using the following URL: http://localhost:8080/. To connect to MySQL you will use the mysql host name:

[crayon-5b76d23287c47393356116/]
 

Thank you! Please let me know in the comments if you have any suggestions to improve this setup or problems running it.


How to Get Nearby Locations from MySQL Database

If you have a MySQL table with locations (latitude and longitude columns) you can get a list of locations near a specific point using the following query:

[crayon-5b76d23289a24659261443/]

In this query we have noted the latitude of the reference point with <latitude>, its longitude with <longitude> and the maximum distance to search for with <distance> (in kilometers).

To make this calculate the distance in miles, just remove the * 1.609344 from the end of the calculation:

[crayon-5b76d23289a31897298673/]

You can test the results using Google Maps. To measure distances in Google Maps you need to right-click and choose “Measure distance” from the popup menu.

How to Get Nearby Locations in Symfony with Doctrine

If you’re like me and use Symfony a lot, here’s how you can add a repository method for your entity to return objects ordered by distance from a specific location:

[crayon-5b76d23289a37322878415/]

To make this work we need to add the ACOS, SIN, COS and PI functions to Doctrine’s DQL as it does not have them by default.

First create 4 new classes in a new AppBundle/DQL folder, one for each function we need to define.

AppBundle/DQL/Acos.php

[crayon-5b76d23289a3e243306812/]

AppBundle/DQL/Sin.php

[crayon-5b76d23289a44295377241/]

AppBundle/DQL/Cos.php

[crayon-5b76d23289a5e197091758/]

AppBundle/DQL/Pi.php

[crayon-5b76d23289a66913013209/]

The next and the last step is to add the above definitions to your app’s config.yml file:

[crayon-5b76d23289a6c401034478/]

That’s it. Now it will all work as expected. If you need to add more specific functions to DQL, just look at the above classes and make your own.


Symfony OAuth Authentication for Your Mobile Application

Let’s say you built an API using Symfony and you need to access it from a mobile application using authenticated requests on behalf of your users.

Here’s how to make this work using Symfony 2.8 and Doctrine.

Install FOSOAuthServerBundle

We will use the FOSOAuthServerBundle to implement this feature. Install it using the following command:

[crayon-5b76d232917b2345201133/]

Next, enable the bundle in the AppKernel.php file:

[crayon-5b76d232917c3903770383/]

Create OAuth model classes

To create the OAuth model classes just add the following files to your project. Here we already have FOSUserBundle installed and set up to use the ApiBundle\Entity\User class.

src/ApiBundle/Entity/Client.php

[crayon-5b76d232917c9590105333/]

src/ApiBundle/Entity/AccessToken.php

[crayon-5b76d232917cf542705844/]

src/ApiBundle/Entity/RefreshToken.php

[crayon-5b76d232917d6374559880/]

src/ApiBundle/Entity/AuthCode.php

[crayon-5b76d232917dc365057532/]

Configure FOSOAuthServerBundle

Import the routing configuration in your app/config/routing.yml file:

[crayon-5b76d232917e2121588001/]

Add FOSOAuthServerBundle settings in app/config/config.yml:

[crayon-5b76d232917e7478068684/]

Back to the models

Generate a migration and migrate the database:

[crayon-5b76d232917ed228650776/]

…or, if you’re not using migrations, just update the database schema:

[crayon-5b76d232917f2151231792/]

Configure your application’s security

Edit your app/config/security.yml file to add FOSOAuthServerBundle specific configuration:

[crayon-5b76d232917f7037448988/]

Create a client

Before you can generate tokens, you need to create a Client using the ClientManager. For this, create a new Symfony command:

[crayon-5b76d232917fd287013006/]

Now run the above command to generate your first OAuth client:

[crayon-5b76d23291804313384978/]

This client will be able to generate tokens and refresh tokens using the user’s username and password. You can find it’s data in the database client table. The token endpoint is at /oauth/v2/token by default.

Document using NelmioApiDocBundle

If you use the NelmioApiDocBundle to document your API, you can add these OAuth methods too. Create a new YAML file in src/ApiBundle/Resources/apidoc/oauth.yml:

[crayon-5b76d2329180a143757089/]

Add a new NelmioApiYmlProvider.php file in src/ApiBundle/Service folder:

[crayon-5b76d23291815487078141/]
Add a new service in src/ApiBundle/Resources/config/services.yml file:
[crayon-5b76d2329181f832117908/]

You’ll find now two /oauth/v2/token methods with different parameters listed in the api/doc section of your project.

That’s all! You can now use the generated client to authenticate your users in your mobile app using OAuth.

How to use the FOSOAuthServerBundle

First you will need to get an access token by making a POST request to the /oauth/v2/token endpoint with the following parameters:

[crayon-5b76d23291826943073009/]

You should get back something like this:

[crayon-5b76d2329182b020281668/]

Use the access token for authenticated requests by placing it in the request header:

[crayon-5b76d23291831666225911/]

When the access token expires, you can get a new one using the refresh_token grant type at the same /oauth/v2/token endpoint:

[crayon-5b76d23291836404015148/]

The response should be similar to:

[crayon-5b76d2329183c748677133/]


tinyint, symfony, doctrine

How to add TINYINT MySQL type to Doctrine in Symfony 2.8

Hello! A few days ago I needed to define an entity with a TINYINT type column to hold a rating value between 1 and 5. I was doing this in a Symfony 2.8 project and to my surprise, Doctrine was unable to handle this type of data out of the box (it uses it for booleans but it has no TINYINT standalone type).

So I searched the internet for a solution and I found some but nothing complete.

The solution (TINYINT vs Doctrine):

First you need to define the new Doctrine type class like this:
[crayon-5b76d232936b6269879191/]
Then, to register it, I used the boot function of the AppBundle:
[crayon-5b76d232936c6762071676/]
I had to use the try / catch block to avoid an error when running symfony console commands having no database defined:

PHP Fatal error: Uncaught exception 'PDOException' with message 'SQLSTATE[42000] [1049] Unknown database 'rating'' in vendor/doctrine/dbal/lib/Doctrine/DBAL/Driver/PDOConnection.php:43

Now you can use the new type in your entities:
[crayon-5b76d232936cd212374199/]

Learn how to setup Docker machine for Symfony development.

Hope this helps someone :)
Have a great day!


Setup Docker Machine for Symfony Development

If you need a development environment for Symfony, hosted by Docker, you can use the fazy/apache-symfony docker image to start with, then extend it to your need.

In your Symfony project's folder add the Dockerfile and docker-compose.yml files.

In the first one, we added mysql and composer, then we used the docker-compose.yml file to mount a local volume to the docker container with file sync.

This way you can code on your machine and test in the docker environment.

The Dockerfile:
[crayon-5b76d23294838220214632/]
The docker-compose.yml file:
[crayon-5b76d23294846345959894/]
To build the Docker container use:

[crayon-5b76d2329484c640579953-i/]

To start it when it's down just remove the --build parameter:

[crayon-5b76d23294852015840658-i/]

Once is running, you can view it's ID by running:

[crayon-5b76d23294857759428073-i/]

Now grab the first 3 characters from the id and use them in the next command to be able to log in the running container:

[crayon-5b76d2329485d662587964-i/]

Finnaly, to access the Symfony project in your browser, go to http://localhost:8080/app_dev.php and have fun!


testing and fixtures

Setup Testing and Fixtures in Symfony2: The Easy Way

Setting up testing and fixtures in Symfony2 is vital if you plan on starting Test Driven Development or you simply want to start covering your code with properly written tests that can access mock data.

 

1. Install PHPUnit and php 5.6

The first thing you need to do is to install PHPUnit on your machine:
[crayon-5b76d23295eeb675781828/]
and then, if needed, also upgrade your PHP version to 5.6:
[crayon-5b76d23295efb955306033/]
and make sure everything's ok by running: phpunit -c app/

Please note that this is not a testing tutorial so if you'd like to learn more about how to actually test your Symfony2 app, then please read their documentation.

 

2. Setup and create a test database

In order to be able to configure testing and fixtures in a Symfony2 app a separate, independent database is needed so that your dev environment is not affected.

In the config_test.yml file you simply need to add:
[crayon-5b76d23295f02950793906/]
then simply run php app/console doctrine:database:create --env=test

 

RelatedSend Emails in Symfony2: The Right Way

 

3. Build the BaseTestSetup class

Once our test database is ready we can start building our BaseTestSetup class, one which will serve as parent for all of our tests.
[crayon-5b76d23295f08887682725/]
 

4. Install the LiipFunctionalTestBundle

Even though Symfony does have an out of the box solution to setup and test your app, the LiipFunctionalTestBundle provides base classes for functional tests to assist in setting up testing and fixtures and HTML5 validation.

After you install and configure the bundle, go back to your BaseTestSetup class and make the necessary modifications:
[crayon-5b76d23295f0e641149620/]
The new code above simply drops and creates the database each them tests run. Then it loads the fixtures that you'll need. The LoadUserData class does not exist yet so we'll go right ahead and add it by following the handy tutorial found on Symfony's website.

 

5. Write the very first test

Now that have your fixtures ready, you can go ahead and write your first test. Create a new file in your AppBundle/Tests folder called UserTest.php, next to BaseTestSetup.php:
[crayon-5b76d23295f16911053698/]
 

And that's about it! You now have everything you need to properly test your awesome app.

 


How to monitor Symfony and Apache logs with M/Monit

So you have developed and deployed a fresh new project and you want to be alerted in case an error happens.

Here's how you do it using the M/Monit tool.

It can be installed on an Ubuntu machine using the following command:
[crayon-5b76d23297260358221101/]
Now edit the /etc/monit/monitrc configuration file and add the following:
[crayon-5b76d2329726f143722681/]
First we need to tell M/Monit what mail server to use (we used Sendgrid but you can use whatever you want), then to specify the email address which will receive the alerts. We also have to allow connections from localhost so the status command below can be executed.

The actual monitoring is set up in the last two blocks of code, one for the apache error log and the next for the Symfony production logs. Anytime the specified string will appear in the logs, an alert email will be sent to the address we defined above.

To enable the changes, reload configuration:
[crayon-5b76d23297276815724894/]
You can now check the status with the command:
[crayon-5b76d2329727c042621246/]
It's that simple!


send emails in symfony2

Send Emails in Symfony2: The Right Way

No matter what your app is about, at one you point you will have to send emails in Symfony2. Even though this process might seem straightforward and easy to apply, it can actually get pretty tricky. Here's how you can send emails in Symfony2 by properly splitting your functionality and templates.

 

1. Mailer parameters

First off, you're going to need to add some email data into your parameters.yml file that will tell Swift Mailer which SMTP server to use. At this point, it would be advised to create an account at an email sending service. For this short tutorial, we're going to use SendGrid.
[crayon-5b76d232981eb517265559/]
As you can see, we've also added three parameters that will help us to send emails in Symfony2: contact email, from email and from name.

 

2. Send emails in Symfony2 using a MailManager

Having a MailManager is helpful because the code needed to send emails will only reside in a single place. Thus, it will be way easier to maintain. Here's how you should build the MailManager class:
[crayon-5b76d232981fa950440712/]
In the sendEmail function, you can easily define a $template variable which will hold whatever template you need, depending on the type of email. You'll see the MailManager in action in the 4th and last section of this short tutorial, where you'll use it to send a contact email.

Oh, and don't forget to register the service in services.yml:
[crayon-5b76d23298202018160445/]
 

Related: Symfony2 Facebook and Google Login: The Easy Way

 

3. Define a simple template

In this section you'll be building the three main blocks any email should have (subject, html and text) and store them in a template which you'll extend as needed.
[crayon-5b76d23298209218816201/]
 

4. A sample email sending action

Now that you have everything set, you can go ahead and build your first mail sending action. As an example, here's how a contact action should look like. It will send emails to the email address defined in parameters.yml.
[crayon-5b76d2329820f251877194/]
Since you'll be using the contact email body, you will need to build it by extending the template defined at step #3:
[crayon-5b76d23298216497808495/]
 

And there you have it - an easy way to build and maintain your emails. If you know of any other easier system used to send emails in Symfony2, please let me know in the comment section below.


APIs in Symfony2

Getting Started with Building APIs in Symfony2

Hello all you Interwebs friends! While we're passing through the shallow mists of time, REST is becoming more and more of a universal standard when building web applications. That said, here's a very brief tutorial on how to get started with building APIs in Symfony2.

Spoiler alert: the bits of code written below use FosUserBundle + Doctrine.

1. Generate a New Bundle

It's nice to keep your code neat and tidy, so ideally, you should create a separate bundle that will only store your API code, we can generically name ApiBundle.
[crayon-5b76d232a1aae985724362/]
 

2.  Versioning

This isn't by any means mandatory, but if you believe that your API endpoints will suffer major changes along the way, that cannot be predicted from the get go, it would be nice to version your code. This means that you would, initially, have a prefix in your endpoints, like: /v1/endpoint.json, and you'd increase that value each time a new version comes along. I'll describe how to actually create the first version (v1) of your API a little further down the line.

3. Install a Few Useful Bundles

  • FosRestBundle - this bundle will make our REST implementation a lot easier.

[crayon-5b76d232a1ac1607621238/]
and then include FOSRestBundle in your AppKernel.php file:
[crayon-5b76d232a1ac7128516592/]

  • JmsSerializerBundle - this will take care of the representation of our resources, converting objects into JSON.

[crayon-5b76d232a1acd022547037/]
and then include JMSSerializerBundle in your AppKernel.php:
[crayon-5b76d232a1ad2266488076/]
 

4. Configurations

Configure the Response object to return JSON, as well as set a default format for our API calls. This can be achieved by adding the following code in app/config/config.yml:
[crayon-5b76d232a1ad7779716444/]
 

5. Routing

I prefer using annotations as far as routes go, so all we need to do in this scenario would be to modify our API Controllers registration in /app/config/routing.yml. This registration should have already been created when you ran the generate bundle command. Now we'll only need to add our version to that registration. As far as the actual routes of each endpoint go, we'll be manually defining them later on, in each action's annotation.
[crayon-5b76d232a1ade295480545/]
At this point we're all set to start writing our first bit of code. First off, in our Controller namespace, we would want to create a new directory, called V1. This will hold all of our v1 API Controllers. Whenever we want to create a new version, we'll start from scratch by creating a V2 namespace and so on.

After that's done let's create an action that will GET a user (assuming we've previously created a User entity and populated it with users). This would look something like:
[crayon-5b76d232a1ae3785067135/]
If we want to GET a list of all users, that's pretty straightforward as well:
[crayon-5b76d232a1ae9235244134/]
With that done, when running a GET request on https://yourapp.com/api/v1/users/1.json, you should get a json response with that specific user object.

What about a POST request? Glad you asked! There are actually quite a few options to do that. One would be to get the request data yourself, validate it and create the new resource yourself. Another (simpler) option would be to use Symfony Forms which would handle all this for us.

The scenario here would be for us to add a new user resource into our database.

If you're also using FosUserBundle to manage your users, you can just use a similar RegistrationFormType:
[crayon-5b76d232a1aef752827348/]
Next, we'll want to actually create our addUserAction():
[crayon-5b76d232a1af5524964003/]
To make a request, you'll need to send the data as raw JSON, to our https://yourapp.com/api/v1/users/new.json POST endpoint:
[crayon-5b76d232a1afb870789720/]
 

And that's all there is to it.

We haven't covered the cases where you'd want Delete or Update a user yet. Updating resources through the REST standards can be done using either PUT or PATCH. The difference between them is that PUT will completely replace your resource, while PATCH will only, well, patch it... meaning that it will partially update your resource with the input it got from the API request.

Let's get to it then. We'll use the same form as before, and we'll try to only change (we'll use the PATCH verb for that) the email address, username and password of our previously created user:
[crayon-5b76d232a1b01752293436/]
The request body is the same as the one shown for the POST method, above. There are a few small differences in our edit action though. First off - we're telling our form to use the PATCH method. Second - we are handling the case where the user ID provided isn't found.

The Delete method is the easiest one yet. All we need to do is to find the user and remove it from our database. If no user is found, we'll throw a "user not found" error:
[crayon-5b76d232a1b07513765240/]

Related: Routing in Symfony2

Conclusions

Aaand we're done. We now have a fully working CRUD for our User Entity. Thanks for reading and please do share your opinions/suggestions in the comment section below.