Jose Armesto's Blog

Continuous Integrating my Kubernetes controller using Kind

Sat, 18 May 2019 23:47:55 +0000

Kubernetes controllers are processes that react to changes in the state of some objects saved on the Kubernetes API. They do this by watching the Kubernetes API so that they get notified whenever the state changes.

But how do we know if our Kubernetes controller is doing what’s supposed to do? We can write unit tests that test our logic in isolation to get some confidence, but it would be great if we could add some end to end tests using the real Kubernetes API.

However, deploying Kubernetes is not an easy task. And even if we managed to accomplish it, it would take a long time to deploy a Kubernetes cluster so we could test every change to our code base.

In this post, I’m going to explain how I used kind to test that my controller is working as expected, using a real Kubernetes API.

Creating the cluster using kind

My Kubernetes controller is pretty simple. Whenever a Deployment object is created containing an specific annotation, it will add an annotation to the Pods belonging to that Deployment. I created this controller because we needed a way for developers to specify that the application that they were deploying required AWS IAM credentials to use AWS services, but we didn’t want developers to have to know things like the AWS account id to use. By using this controller, the Kubernetes cluster administrators configure which AWS Account to use on every Kubernetes namespace. And developers just indicate whether their application requires IAM authentication or not, by adding an annotation. Simple.

Anyway, I wanted to create an end to end test that would do the following:

Create a Kubernetes cluster
Install the controller using the version that we are testing
Create a Deployment that contains the annotation that will trigger the controller
Test that the Pods of the Deployment contain the IAM annotation

For the Kubernetes cluster I used kind, a recent project that let’s you deploy a Kubernetes cluster using only a Docker container. Obviously, it’s not meant to be used on production, but it’s perfect for testing purposes. To create a cluster with kind, you just need to

$ kind create cluster

And that’s it! It’s that simple. We can see the cluster is running inside a single container

$ docker ps
CONTAINER ID        IMAGE                  COMMAND                  CREATED             STATUS              PORTS                                  NAMES
c27f2c8fa39e        kindest/node:v1.14.1   "/usr/local/bin/entr…"   22 minutes ago      Up 22 minutes       63711/tcp, 127.0.0.1:63711->6443/tcp   kind-control-plane

Now you just need to make kubectl send requests to that cluster, using the command

$ export KUBECONFIG="$(kind get kubeconfig-path)"

I’m also creating a new Namespace where I’ll run all the things required for this test. This is not important during Continuous Integration (CI), where everything will be deleted when the CI job is finished. But I do it this way because I can then easily run the same test locally on other Kubernetes clusters like Minikube, while not on CI. When the test is done, I just remove the namespace to leave no traces of the test execution.

Installing my controller

Now I need to install the piece of code that I want to test: my controller. The controller repository contains a Helm chart to make it easy to install it, so I’ll just use it. That way, I’m also testing whether or not the Helm chart is working as expected.

$ helm upgrade --tiller-namespace ${NAMESPACE} --namespace "${NAMESPACE}" --wait --install "iam-role-annotator" "./charts/iam-role-annotator" --set image.tag="${TRAVIS_COMMIT:-latest}" --set awsAccountId="${AWS_ACCOUNT_ID}"

The value for the AWS_ACCOUNT_ID variable is important. It’s the same AWS Account Id that needs to be added as annotation on applications. Notice that I passed the --wait argument to Helm. This will block the command until my controller is running and ready. If it fails to start for whatever reason, the test would automatically fail.

Create annotated deploy and check the results

My controller is ready and waiting for applications that contain the right annotation. Creating a simple hello world application containing that annotation is enough to trigger my controller. Let’s use a simple nginx deployment

$ cat <<EOF | kubectl create -f -
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deploy
  namespace: ${NAMESPACE}
  labels:
    app: nginx
  annotations:
    armesto.net/iam-role-annotator: "true"
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
      annotations:
        prometheus.io/scheme: http
    spec:
      containers:
      - name: nginx
        image: nginx:1.7.9
        ports:
        - containerPort: 80
EOF

Notice the important annotation for my controller: armesto.net/iam-role-annotator: true.

Now I just need to wait for my controller to react.

Then I can test if the pods belonging to the hello world deployment contain the required annotation. For that I used jq, a handly command line tool to inspect json data.

POD_NAME=$(kubectl get pods --namespace ${NAMESPACE} --field-selector=status.phase=Running -l "app=nginx" -o jsonpath="{.items[0].metadata.name}")

if [[ $(kubectl get pod --namespace ${NAMESPACE} ${POD_NAME} -o json | jq '.metadata.annotations' | jq 'contains({"iam.amazonaws.com/role"})') == 'true' ]]; then
  if [[ $(kubectl get pods --namespace ${NAMESPACE} ${POD_NAME} -o json | jq -r '.metadata.annotations."iam.amazonaws.com/role"') == "arn:aws:iam::${AWS_ACCOUNT_ID}:role/${DEPLOYMENT_NAME}" ]]; then
    echo "SUCCESS!"
    exit 0
  else
    echo "ERROR: the annotation contains the wrong value"
    kubectl get pod --namespace ${NAMESPACE} ${POD_NAME} -o json | jq '.'
    exit 1
  fi
else
  echo "ERROR: the POD does not contain the expected annotation"
  kubectl get pod --namespace ${NAMESPACE} ${POD_NAME} -o json | jq '.'
  exit 1
fi

Conclusion

Every time I push some changes to this controller, the CI pipeline kicks in, and my end to end test gets executed creating a Kubernetes cluster thanks to kind.

Now I have much more confidence that my changes will work as expected when deploying the controller to our production clusters, and that makes a huge difference.

Automatically versioning your Application on Jenkins X

Fri, 01 Feb 2019 23:47:55 +0000

Having a good versioning strategy for our applications is key. Specially in Jenkins X, which follows the GitOps flow to deploy our applications, specifying which version of our application will be used on each environment.

But having to manually create tags or releases for our applications can be a tedious task. Jenkins X automatically takes care of versioning for us. It uses a tool called jx-release-version to figure out which is the next version to be released. In order to do that it checks what’s the current released version in the repository looking at the released Git tags. It can also read this version from your pom.xml file, or your Makefile.

If we use semver semantics, and versions are written in the format major.minor.patch, jx-release-version will tell you which is the next patch version.

The cool thing is that you don’t need to use Jenkins X to use jx-release-version!

Let’s go through some examples.

Using git tags

Using git tags is probably the easiest way to handle our application versions. We can create a new git tag for every new version that we want to release.

If we try to use jx-release-version on a Git repository that has no tags, it will return that the next version number to release is 0.0.1. Next time we use jx-release-version, it will increase our patch number.

$ git --no-pager tag -l
$ # there are no tags just yet!
$ RELEASE_VERSION=`jx-release-version` && git tag -fa v${RELEASE_VERSION} -m 'Release version ${RELEASE_VERSION}'
$ git --no-pager tag -l
v0.0.1
$ RELEASE_VERSION=`jx-release-version` && git tag -fa v${RELEASE_VERSION} -m 'Release version ${RELEASE_VERSION}'
$ git --no-pager tag -l
  v0.0.1
  v0.0.2

Using maven pom file

If you are using a pom.xml file that also tracks your current application version, you still can use jx-release-version. It will try to sync the git tags in your Git repository with the version that you specify in the pom.xml file.

Your release process needs to look something like this

# First we call the `jx-release-version` binary that will return the next version number to be released.
# Every time we call the binary it will try to figure out the next version number. Normally it's not a good idea to call it more than once.
RELEASE_VERSION=`jx-release-version`
echo "New release version ${RELEASE_VERSION}

# We update our current pom.xml file with this new version number.
mvn versions:set -DnewVersion=${RELEASE_VERSION}

# Changes to the pom.xml file need to be committed to our repository.
git commit -a -m 'release ${RELEASE_VERSION}'

# The git commit containing both our application changes and the change to the pom.xml file will be tagged using the same version number.
git tag -fa v${RELEASE_VERSION} -m 'Release version ${RELEASE_VERSION}'

# Push the commit and tag to the remote repository.
git push origin v${RELEASE_VERSION}

If we start a new git repository that has no tags, the jx-release-version will use the version in our pom.xml file.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>io.example</groupId>
    <artifactId>example</artifactId>
    <version>1.0-0-SNAPSHOT</version>
    <packaging>pom</packaging>
</project>

The release version for 1.0.0-SNAPSHOT is 1.0.0, so jx-release-version will return 1.0.0 as the next version number to use. Similarly, if our pom.xml file had <version>0.0-23-SNAPSHOT</version> in it, jx-release-version would return 0.0.23 as the next version number to use.

Using a Makefile

Let’s say we have this Makefile that tracks the current version of our application

# This is the current version of your application
VERSION := 2.0.3-SNAPSHOT

# Use jx-release-version to calculate next version
RELEASE_VERSION := $(shell jx-release-version)

build:
	# The git commit containing our application changes will be tagged.
	git tag -fa v${RELEASE_VERSION} -m 'Release version ${RELEASE_VERSION}'

	# Push the tag to the remote repository.
	git push origin v${RELEASE_VERSION}

The current version of our application is 2.0.3-SNAPSHOT. That means that the jx-release-version will return 2.0.3 as the next version number to use.

Releasing a new major/minor version

Sometimes we don’t want to just release a new patch version (like going from 1.0.5 to 1.0.6). Instead, we want to release 1.1.0, or even 2.0.0. We have said earlier that jx-release-version calculates the next version number based on the current Git tag, or current specified version on pom.xml/Makefile. So if we need to release a new major/minor version, we just have to release a new Git tag or update the pom.xml/Makefile.

For example, if the current version is 0.0.2 and we want to release 0.1.0, we first create a git tag for that and let jx-release-version do it’s thing afterwards.

# Manually create new tag for the version that we want
git tag -fa v0.1.0 -m "Release version 0.1.0"
# Use jx-release version normally
$ RELEASE_VERSION=`jx-release-version` && git tag -fa v${RELEASE_VERSION} -m 'Release version ${RELEASE_VERSION}'
$ git --no-pager tag -l
v0.0.1
v0.0.2
v0.1.0
v0.1.1

As said in the project’s README

If your project is new or has no existing git tags then running jx-release-version will return a default version of 0.0.1
If your latest git tag is 1.2.3 and you Makefile or pom.xml is 1.2.0-SNAPSHOT then jx-release-version will return 1.2.4
If your latest git tag is 1.2.3 and your Makefile or pom.xml is 2.0.0 then jx-release-version will return 2.0.0

Jenkins X Environments

Wed, 05 Dec 2018 23:47:55 +0000

This year Jenkins X has been announced. If you haven’t heard, Jenkins X is a tool that lets you automate the whole delivery process of your software to a Kubernetes cluster. One key aspect of Jenkins X is that the deployment of applications is implemented following the GitOps flow. In this approach every environment is represented by a Git repository. In this post we’ll see how Jenkins X environments work.

Environments

An installation of Jenkins X consists of:

A Development Environment which is a kubernetes namespace running tools like Jenkins, Nexus, etc. Each different team within an organization is meant to have its own development environment so that they can be as independent from each other as possible.
Other Permanent Environments which are kubernetes namespaces where our applications will be deployed into. By default Staging and Production are created. Each team can have as many Permanent Environments as they wish and call them whatever they like.
Optional Preview Environments, which are kubernetes namespaces where our applications will be deployed, just like Permanent Environments, but these are created on a PR basis, before you even merge your PR changes into master.

Under the covers this is implemented creating a custom Kubernetes resource jenkins.io/v1/Environment. Assuming that each team has a Kubernetes namespace assigned, each team will normally have a Development Environment and several different Permanent Environments. Each of these environments is represented by a jenkins.io/v1/Environment object on the namespace assigned to that team.

Teams are also represented by a jenkins.io/v1/Team object, but we will cover that on a different post.

These Environment objects contain configuration about which Git repository is associated with it, and which git branch to use.

There could be one namespace which is where all apps run across all teams - though from a kubernetes RBAC perspective, if you are working in microservices teams, it’s better for each team to manage their own microservices in their own production environment and use service linking between teams.

Development Environment

A jenkins.io/v1/Environment object created on the team’s namespace, which spec.Kind field is Dev. This environment is not linked to a Github repository, we will never promote changes here. It’s just a Kubernetes namespace used to run applications while developing, thanks to skaffold.

In the dev environment Jenkins X installs a number of core applications they believe are required at a minimum to start folks off with CI/CD on Kubernetes. They come with configuration that wires these services together meaning everything works together straight away.

Jenkins — provides both Continuous Integration and Continuous Delivery automation.
Nexus — acts as a dependency cache for applications to dramatically improve build times.
Docker registry — an in cluster Docker registry where the pipelines push application images.
Chartmuseum — a registry for publishing Helm charts.
Monocular — a UI used for discovering and running Helm charts.

Permanent Environments

These environments are where the applications will ran. By default Staging and Production are created, but more environments can be created. Staging has the Auto promote strategy and Production the Manual promote strategy. We’ll see what that means in a minute.

These environment are linked to

A GitHub repository containing a Helm chart that defines which application charts are to be installed on the environment, which versions of them and any environment specific configuration and additional resources (e.g. Secrets or operational applications like Prometheus etc).
A Kubernetes namespace where the Helm chart from the repository will be installed.

When you want to deploy to an environment, a Pull Request must be made to that environment’s repository. We can manually create the PR to deploy an application to an environment, or we can use this handy jx command

jx promote --app myapp --version 1.2.3 --env production

Typically we specify the environment while promoting to environments with the Manual promote strategy, like the Production environment. Instead of specifying the environment, we can create a Pull Request in all the environments having the Auto promote strategy using this jx command

jx promote -b --all-auto --timeout 1h --version \$(cat ../../VERSION) --no-wait

Changing the Production environment’s promote strategy from Manual to Auto you can do Continuous Deployment.

When these PRs are merged into the environment’s git repository, the environment pipeline runs, which then applies the Helm chart living on that repo to the environment’s Kubernetes namespace.

Preview Environments

Preview Environments are similar to Permanent Environments in that they are defined in a source code Git repository using Helm charts. The main difference is that Preview Environments are configured inside the application repository in the ./chart/preview folder. Also they are not permanent but created when a Pull Request is made to an application’s git repository, and then deleted some time after (manually or via automatic garbage collection).

When the Preview Environment is up and running Jenkins X will comment on your Pull Request with a link so in one click your team members can try out the preview.

You can create a preview environments using

jx preview

This will create the Environment and Namespace objects for this environment. It will also build the application creating a new Docker image that will be deployed to the preview environment using the preview chart defined in the ./chart/preview folder.

Managing environments

You can create new environments using jx

jx create env --name prod --label Production --namespace my-prod

Some interesting options are

label: The Environment label which is a descriptive string like Production or Staging.
prefix: Environment repo prefix, your Git repo will be of the form environment-$prefix-$envName.
promotion: The promotion strategy, Auto or Manual.

You can then list all existing environments

jx get environments

Or edit an existing environment (-b for no interactive)

jx edit env -b --name prod --label Production --no-gitops --namespace my-prod

Or finally delete it

jx delete environment prod

Deployment Flow

In the workflow that Jenkins X proposes, we will have a repository for each application that we want to deploy. But also we will have a repository for each environment where you want to deploy these applications. The repositories for the different environments describe all the applications that must be running on them.

So while developing your application, the usual flow would be

Create a Pull Request on the application repository: this will execute the application CI pipeline to build and test the application.
Once the Pull Request on the application repository is merged, the application pipeline will release this newly built version to a Docker Registry and promote it to the environments with the Auto promote strategy using a jx command.
If we want to deploy to production or any environment with the Manual promotion strategy, we need to execute the jx command targeting the desired environment.

Layered architecture and Kubernetes operators

Mon, 03 Dec 2018 23:47:55 +0000

If you’ve been developing applications for some time, you’ve probably developed some kind of HTTP application. This is the most solved problem there is in our industry, with lots of frameworks and tools that help you solve this problem easily. Also, there are some patterns and practices that we apply when solving this, that come from years of experience learning the pain points while developing these applications. I’m talking about things like not coupling your business rules to your framework, or using layers to separate things like data access objects from your domain model.

However, sometimes we forget that we can apply these patterns to almost any kind of software project. Lately I’ve been involved in projects that contain some Kubernetes Operators and the code in there could benefit a lot from the patterns that we already apply to our typical HTTP applications.

Don’t let your domain model depend on your framework

I created this Kubernetes controller some months ago. There are several different frameworks to help you create your own Kubernetes Operator/Controller, but in this particular case, I decided to try Kooper. If I search the keyword “kooper” in the codebase of my controller, there are only two matches: the dependency file declaring the dependency on the kooper library, and the main file that bootstraps the controller. All the other files (specially the pkt/service.go file containing all the business logic) don’t depend on the kooper framework at all. If I would switch to a different framework, I wouldn’t need to change pretty much anything, only the bootstrapping of the process that takes care of all the wiring. All the important bits, the business logic containing what my controller actually does, that wouldn’t need to be rewritten or even touched.

You are using a database, believe it or not

Kubernetes Operators and Controllers use the Kubernetes API to get the current state of the cluster, and store data on inside Kubernetes resources. This means that these processes are using etcd as a database, which we normally access through the Kubernetes API using the client-go library.

In other kind of applications, we have been creating specific objects that take care of accessing our data for years. We usually call these objects the data access layer, but somehow we don’t do it when accessing the data stored in Kubernetes objects. It’s pretty normal to find code like this all over a Kubernetes operator or controller

We are coupling our business logic to the client-go library that we use to talk to the Kubernetes API. This makes our Kubernetes operators and controllers hard to test, because when this code is executed, it will try to connect to a real Kubernetes cluster. The client-go library offers some tooling to help you create Fake API’s, but wouldn’t be better if we wouldn’t need to use that to test every part of our application?

By encapsulating the data access parts of your code on its own objects, you could write unit tests for the important bits of your application where the business logic is happening, easily stubbing the data access objects. We could use the Repository pattern for this. This is a repository to fetch ConfigMaps from the Kubernetes API. That’s the real implementation that my controller will use when it’s started. But this is the implementation that my controller will use when running the unit tests. This fake implementation won’t try to connect to a real Kubernetes cluster: it just stores the objects in memory, which is fine to run our tests.

We would still need to write some integration tests, to make sure that everything works well together. But all the complexity of testing your code depending on the client-go library, would only affect your repository objects.

Dependency injection

In order to achieve what we’ve been talking about on this post, it’s really important that we use dependency injection to pass the right objects to our methods. We need to be able to pass either the real data access objects or the stubbed ones.

Instead of instantiating the objects that your service depends on inside its own functions, declare those dependencies as parameters that need to be passed when creating the service. This way you can pass the right implementation that you need. On your unit tests, pass the stubbed implementation. On the real bootstrapping of your service, pass the real implementation that talks to the Kubernetes API, like this

This service doesn’t care if the client is the real one or the stubbed one.

Conclusion

At the end of the day, it’s just applying what we have already been applying to our applications for years. As Kubernetes controllers and operators get more complex, a better structure for our code is needed to keep the code maintainable.

I didn't know you could do that with a Dockerfile!

Tue, 30 Oct 2018 23:47:55 +0000

Docker released the multi-stage builds feature in the version 17.05. This allowed developers to build smaller Docker images by using a final stage containing the minimum required for the application to work. Even though this is being used more and more over time, there are still multi-stage patterns that are not that widely used.

In this post I’ll show you how to use multi-stage builds to:

avoid having different Dockerfiles for every environment
copy files from remote images
use parameters in the FROM image

Multi-stage builds allow us to use the FROM keyword in several places of the same Dockerfile. Every time we use the FROM keyword a new stage will be created. One important thing is that we can name these stages to refer to them later on in the Dockerfile.

You don’t need a Dockerfile for each environment

Imagine the following scenario: you need certain tools installed on the Docker image that you will use for development, but you don’t want those tools on the final image that will be deployed in production. For example, when developing in PHP it’s useful to have xdebug installed, but you normally don’t need it in production.

# Use this image as the base image for dev and prod.
FROM php:7.2-apache as common

# The pdo_mysql extension is required for both dev and prod.
RUN a2enmod rewrite; \
    chown -R www-data:www-data /var/www/html; \
    docker-php-ext-install pdo_mysql;

# Here we configure PHP, but this configuration will be overwritten for prod.
COPY php.ini /usr/local/etc/php/php.ini


# In this image we will download the dependencies, but without the development dependencies.
# The dependencies are installed in the vendor folder that will later be copied.
FROM composer as builder-dev

WORKDIR /app

# Copy only the files needed to download dependencies to avoid redownloading them when our code changes.
# This will download development/testing dependencies.
COPY composer.json composer.lock /app/
RUN composer install  \
    --ignore-platform-reqs \
    --no-ansi \
    --no-autoloader \
    --no-interaction \
    --no-scripts

# We need to copy our whole application so that we can generate the autoload file inside the vendor folder.
COPY . /app
RUN composer dump-autoload --optimize --classmap-authoritative


# This is the image using in development.
FROM common as dev

# We only install xdebug in development.
RUN pecl install xdebug-2.6.0; \
    docker-php-ext-enable xdebug

WORKDIR /var/www/html

# We enable the errors only in development.
ENV DISPLAY_ERRORS="On"

# Copy our application.
COPY . /var/www/html/
# Copy the downloaded dependencies from the previous stage.
COPY --from=builder-dev /app/vendor /var/www/html/vendor
# Setup PHP for development.
COPY php-dev.ini /usr/local/etc/php/php.ini
RUN composer dump-autoload --optimize --classmap-authoritative


# In this image we will download the dependencies, but without the development dependencies.
# The dependencies are installed in the vendor folder that will be copied later into the prod image.
FROM composer as builder-prod

WORKDIR /app

COPY composer.json composer.lock /app/
RUN composer install  \
    --ignore-platform-reqs \
    --no-ansi \
    --no-dev \
    --no-autoloader \
    --no-interaction \
    --no-scripts

# We need to copy our whole application so that we can generate the autoload file inside the vendor folder.
COPY . /app
RUN composer dump-autoload --optimize --no-dev --classmap-authoritative

# This is the image that will be deployed on production.
FROM common as prod

# Add label and exposed port for documentation.
LABEL maintainer="Jose Armesto <jose@armesto.net>"
EXPOSE 80

# No display errors to users in production.
ENV DISPLAY_ERRORS="Off"

# Copy our application
COPY . /var/www/html/
# Copy the downloaded dependencies from the builder-prod stage.
COPY --from=builder-prod /app/vendor /var/www/html/vendor

Building our application image

When building the Docker image now we can choose which stage to build. The stages that will be executed depend on which stage we choose to build and the order in which these stages are defined in the Dockerfile.

If we are developing and need our dev version of the application, we can build the Docker image like

$ docker build --tag "my-awesome-app" --target "dev" .

This will only execute the Dockerfile lines of the stage named dev, and the stages that appear right before it: common and builder-dev. If we would’ve placed the builder-prod stage before the definition of the dev stage (right after the builder-dev stage), the builder-prod stage lines would’ve got executed when building the dev stage, even though we don’t need them. So make sure to plan ahead and put the stages in the right order: every stage related to dev will be placed before any stage related to prod.

If we need the prod version that will be deployed in production, we can pass the prod target or just don’t pass any target at all

$ docker build --tag "my-awesome-app" .

This will execute all the instructions in the Dockerfile, because the prod stage is the last one to appear on the Dockerfile.

Can we improve the building speed for development?

It seems that building our docker image for development is kind of slow. Can we make it faster? Our approach is copying our application files several times from our laptop to the image layer, making the process slow. And it will be slower as our application grows.

We can merge the builder-dev and the dev stages into one big stage to reduce the number of times we copy our application. Let’s remove the builder-dev stage and change our dev stage to this

# In the development image we download dependencies and copy our code to the image.
FROM common as dev

# We only want xdebug in development.
# We need to install some tools required by Composer, which will run in this stage.
RUN apt-get update; apt-get install -y wget zip unzip git; \
    pecl install xdebug-2.6.0; \
    docker-php-ext-enable xdebug; \
    wget https://raw.githubusercontent.com/composer/getcomposer.org/1b137f8bf6db3e79a38a5bc45324414a6b1f9df2/web/installer -O - -q | php -- --install-dir=/usr/bin --filename=composer --quiet

WORKDIR /var/www/html

# Copy only the files needed to download dependencies to avoid redownloading them when our code changes
COPY composer.json composer.lock /var/www/html/
RUN composer install  \
    --ignore-platform-reqs \
    --no-ansi \
    --no-autoloader \
    --no-interaction \
    --no-scripts

# We enable the errors only in development
ENV DISPLAY_ERRORS="On"

# Copy our application. Now the dependencies are already there.
COPY . /var/www/html/
# Setup PHP for development.
COPY php-dev.ini /usr/local/etc/php/php.ini
RUN composer dump-autoload --optimize --classmap-authoritative

Our development image will contain Composer (and wget, zip…) too, but I think that’s not a big deal in this scenario.

Parametrized image tags

Did you know that you can use parameters for the base image to use when building your image? We can define a parameter that sets the PHP version to use

ARG PHP_VERSION=7.2

FROM php:${PHP_VERSION}-apache as common
# Here would go the rest of the Dockerfile
# ...

Then just pass the right PHP version to use when building the image. If we want to use PHP v7.1 instead

$ docker build --tag "my-awesome-app" --build-arg "PHP_VERSION=7.1" .

Combine targets with docker-compose

The reality is that many people use docker-compose while developing locally because it makes it really easy to start other containers along with your application, like a database that your application needs to store information. In this scenario you can tell docker-compose to build your image and which target to use.

version: '2.4'
services:
  web:
    build:
      context: .
      target: dev
      args:
        PHP_VERSION: ${PHP_VERSION}
    ports:
      - 8000:80
    volumes:
      - .:/var/www/html
    depends_on:
      - postgres
  postgres:
    image: postgres:11.0-alpine
    environment:
      POSTGRES_USER: dbuser
      POSTGRES_DB: my-db

You can now fire up your application and its dependencies as usual, but you can pass the desired PHP version as an environment variable

$ PHP_VERSION=7.1 docker-compose up --build

Copying from remote images

We have seen how to copy files from previously generated layers. But did you know that you can copy files from remote images?

For example, instead of installing Composer in our dev stage, we could just copy it from the official Composer image

# In the development image we download dependencies and copy our code to the image.
FROM common as dev

# We only want xdebug in development.
# We need to install some tools required by Composer, which will run in this stage.
RUN apt-get update; apt-get install -y zip unzip git; \
    pecl install xdebug-2.6.0; \
    docker-php-ext-enable xdebug;

# Copy composer binary from official Composer image.
COPY --from=composer /usr/bin/composer /usr/bin/composer

WORKDIR /var/www/html

# Copy only the files needed to download dependencies to avoid redownloading them when our code changes
COPY composer.json composer.lock /var/www/html/
RUN composer install  \
    --ignore-platform-reqs \
    --no-ansi \
    --no-autoloader \
    --no-interaction \
    --no-scripts

# We enable the errors only in development
ENV DISPLAY_ERRORS="On"

# Copy our application. Now the dependencies are already there.
COPY . /var/www/html/
# Setup PHP for development.
COPY php-dev.ini /usr/local/etc/php/php.ini
RUN composer dump-autoload --optimize --classmap-authoritative

Introducing Wimpy

Sat, 20 May 2017 21:00:31 +0000

Today I want to share with you the project I’ve been working on for the last year in my free time. For me, the project has already been a success: it’s a pet project that has allowed me to learn a lot about Amazon Web Services, Docker and Ansible. But letting that aside, I believe is a useful project that can help you deploy your software better!

Wimpy is an open source Platform as a Service that you run from your terminal to deploy your applications to AWS, following cloud best practices.

Heavily inspired on the great Ansistrano, it’s built as a set of Ansible roles and it’s executed using an Ansible playbook in your application’s repository.

Wimpy’s goal is to make it easy to follow AWS best practices, embracing immutable infrastructure patterns where your servers are considered to be immutable. Whenever a new version is released, the servers get never updated but replaced by new servers containing the new released version.

Usage

Let’s see an example for a playbook, where you can configure how Wimpy will deploy your application:

- hosts: all
  connection: local
  vars:
    # Name of the application, used to name resources in AWS
    wimpy_application_name: "awesome-application"
    # Where your application is listening for HTTP requests
    wimpy_application_port: "80"
    # It will create a new DNS for awesome-application.armesto.net
    wimpy_aws_hosted_zone_name: "armesto.net"
  roles:
    - role: wimpy.environment
    - role: wimpy.build
    - role: wimpy.deploy

Now you can just run the playbook using Ansible, or, if you don’t have Ansible installed, you can just use our Docker image that contains Ansible and all Wimpy roles:

$ docker run -v /var/run/docker.sock:/var/run/docker.sock \
    -v "$PWD:/app" fiunchinho/wimpy /app/deploy.yml \
    --extra-vars "wimpy_release_version=`git rev-parse HEAD` \
                  wimpy_deployment_environment=production"

In this case, there are two variables that we want to pass on every deploy we make: the version being deployed and in which environment we want to deploy it. In this case, the version being deployed is the SHA1 commit hash from Git, but you can choose any arbitrary tag for your version, like “v1.4.2” or whatever.

Once executed, you can browse to http://awesome-application.armesto.net to see your application, and you will have a bunch of resources in your AWS account.

What happened

As I said earlier, Wimpy has been build with modularity in mind, so it’s not an all-or-nothing kind of tool. You can choose which roles to execute. Let’s see what these roles do.

wimpy.environment

First of all, this role will enable CloudTrail for your account, an audit log so you can track who-did-what-when in your account. It also registers a master key in KMS for applications to encrypt and decrypt secrets.

Your AWS account must be prepared before you can deploy your applications. By executing this role, your accout gets two different isolated environments called staging and production. Each environment gets its own Virtual Private Cloud, meaning that applications in one environment can’t connect to applications in a different environment. Total isolation between environments right from the start.

The same applies for S3. Wimpy creates a single bucket for all your applications, but each application will only be able to access the application folder in the environment where is running. For example, if your S3 bucket is called storage, the application called cats-api will have access to the storage/production/cats-api/ folder when deployed in production, but it will have access only to storage/staging/cats-api/ when deployed in the staging environment.

Last but not least, this role creates the needed security groups to allow traffic to your applications:

From the internet to the Load Balancer specified port.
From the Load Balancer to your application exposed port.
From the application to the databases.

By default, any other access it not allowed, so for example, databases can’t be accesed from the internet.

wimpy.build

Docker is not only great for running applications but for packaging as well. By using Docker for packaging, Wimpy is language agnostic and can deploy any application written in any language.

By default, this role will use an Elastic Container Registry on AWS to store your applications images, but you can choose any Docker Registry that you like.

On every deployment, it will package your application as a Docker image that can be run anywhere. Not only is available for the deployments in production, but different teams within your organization can start sharing their applications to make development easier.

wimpy.deploy

This is probably the most interesting part! This role will deploy your application as an Auto Scaling Group with Scaling Policies that will scale up and down the number of instances. Each instance will run the application’s Docker container, supervised by systemd.

If you want, it will create a new Route53 DNS register pointing to your Load Balancer, which will balance the traffic between all the instances in your Auto Scaling Group.

The end result would be something like this:

The role offers two different deployment strategies.

Rolling Update

Using this deployment strategy, we rely on the built-in Rolling Update mechanism for Auto Scaling Groups, where each instance of the Auto Scaling Group is replaced by a new instance that contains the version being deployed.

If something fails while replacing old instances with new ones, AWS will handle the rollback for us.

Blue / Green (Red / Black) deployment

In this strategy, we create a new CloudFormation for every deploy. This means that every deploy will generate a new Auto Scaling Group (which instances contain the version being deployed), a new Load Balancer and a new DNS register. Since now we have two different registers for the same domain name (one for each version deployed), Wimpy uses Route53 weighted registers to control how much traffic goes to every version.

You can tune how much traffic goes to new versions, so you can use this feature for canary releases. This is great for testing in production with real traffic.

Example

I’ve two examples that show Wimpy in action

Fork of the Symfony demo project, but adding Wimpy to deploy the application from Travis.
Fork of the Spring pet-clinic demo project, also just adding Wimpy to be executed on every merge to master.

Summary

Wimpy tries to help you automate your deployments and infrastructure best practices in the AWS, making sure that different teams within your organization all deploy applications the same way.

It’s composed by different roles that you can combine, or even extend, building your own roles/tasks.

Everything is created on your own AWS account. That means that you are in full control of your resources, and if you don’t want to use Wimpy anymore, you won’t lose anything.

You can learn more about the project in the documentation page. Feel free to read through the code in the Github organization. Contributions are really welcomed!

Acknowledgements

Finally, I’d like to thank all the people that have helped me during the development of this project. This would’ve never happened without them, specially:

Stackless Exceptions

Sat, 28 Jan 2017 20:00:31 +0000

Este es un post corto donde os enseñaré qué son y por qué son utiles las Stackless Exceptions, o excepciones que no contienen stack trace.

Controlando el flujo de la aplicación con excepciones

Digo que es un post corto porque podríamos entrar en el debate sobre si es buena práctica o no el utilizar excepciones en el código para dirigir el flujo de la aplicación. Con esto me refiero, por ejemplo, a lanzar una excepción cuando el usuario intenta gastarse más dinero del que tiene en la cuenta, y que una clase de otra capa se encargue de capturar esa excepción. Yo es un patrón que sí utilizo, aunque soy consciente de que mucha gente cree que es un anti patrón, argumentando que es más difícil seguir el flujo del programa, y que es más caro lanzar excepciones que simplemente devolver errores. De hecho, el lenguaje Golang no permite lanzar excepciones, sino que cada llamada a una función devuelve dos valores: el valor en caso de éxito, y el valor en caso de error. Con esto se intenta conseguir que el flujo de la aplicación sea lineal y fácil de seguir.

Aunque como digo, no voy a entrar en ese debate, sí es cierto que una de los argumentos es el coste de lanzar una excepción. Si esto es lo que nos preocupa, hay una manera de lanzar excepciones que las hace practicamente gratis: las stackless exceptions.

Muchas veces no nos importa dónde se haya lanzado una excepción. Lo que nos importa realmente es que se ha lanzado. Siguiendo con el ejemplo antes mencionado, imaginad una excepción de negocio que se lanza cuando el usuario intenta realizar un pago pero no tiene suficiente dinero en su cuenta. Normalmente lanzamos esa excepción para capturarla en una capa superior de la aplicación, pero no es una excepción que necesitemos saber dónde se ha lanzado. Por tanto, puedo ahorrarme el stack trace, que, precisamente, es lo que más cuesta a la hora de construir excepciones.

Esta excepción es igual que cualquier otra, con la única diferencia de que no tiene stack trace.

Creando Stackless Exceptions

Aquí vemos un ejemplo de una excepción que no tendrá información de stack

public class NotEnoughMoneyException extends Exception {

    public StacklessException(String message) {
        super(message);
    }

    /**
     * Does not fill in the stack trace for this exception
     * for performance reasons.
     *
     * @return this instance
     * @see java.lang.Throwable#fillInStackTrace()
     */
    @Override
    public Throwable fillInStackTrace() {
        return this;
    }
}

Lo que hacemos para crear la excepción NotEnoughMoneyException, es sobreescribir el método fillInStackTrace(), que es el encargado de guardar esa información. Al sobreescribirlo y que no haga nada, no tendremos stack trace.

Incluso podrías tener la excepción llamada StacklessException, y hacer que las excepciones de negocio donde no te interesa el stack trace, hereden de ésta, y no repetir esto en cada excepción. Aunque esto ya es al gusto de cada uno.

Conclusión

El debate sobre si utilizar excepciones para controlar el flujo de la aplicación sigue ahí, pero el argumento del coste de las excepciones desaparece con esta técnica, donde quitamos el peso del stack trace.

Problemas desplegando código si usas Apache, symlinks y opcache

Fri, 01 May 2015 12:14:32 +0000

Muchas de las soluciones disponibles en el mercado para desplegar aplicaciones se basan en el uso de enlaces simbólicos (o symlinks) para activar la última versión de código en el servidor.

Simplificando mucho, podríamos decir que un flujo habitual a la hora de desplegar sería el siguiente:

Ejecutamos comando para iniciar el proceso de despliegue de código nuevo.
Se descarga el código del repositorio y se construye la aplicación. Esto suele significar instalar dependencias, generar ficheros, etc.
Se mueve el resultado del paso anterior al servidor y se pone en una carpeta nueva.
La carpeta a la que apunta el document root de nuestro servidor web es en realidad un enlace simbólico a otra carpeta que contiene código en la versión anterior. Por tanto solo nos queda cambiar ese enlace simbólico para que apunte a la nueva que acabamos de crear.

Como el cambio de enlace simbólico es practicamente instantáneo, conseguimos reducir la ventana de tiempo en la que el servidor está en un estado inconsistente, por ejemplo, porque todavía no se hayan terminado de copiar ficheros. Mientras se están subiendo la versión nueva, seguimos sirviendo la versión vieja, sin dejar de dar servicio. Y solo cuando la nueva está lista, hacemos el cambio de forma casi instantánea.

Problemas con este enfoque

Esta manera de desplegar, que parece sencilla y perfecta, tiene algunas complicaciones. Con la que la gente más suele pelearse es con el hecho de que a pesar de haber desplegado una versión nueva en el servidor, a veces siguen viendo la versión vieja, debido a la extensión Opcache (antiguo APC) que guarda la compilación del código PHP interpretado en memoria. Por tanto, aunque la versión nueva ya está activa, PHP sigue tirando de esta caché para no tener que leer del disco y volver a compilar código PHP, así que se sirve el código de la versión vieja hasta que caduque esta caché (si es que lo tenemos configurado para que caduque), o hasta que reiniciemos el servidor dejando de dar servicio mientras dure el reinicio del servidor.

Antes de ver cómo solventarlo, vamos a ver un par de detalles interesantes.

Te presento a tu nueva amiga realpath_cache

Cada vez que utilizas una ruta del sistema de archivos, por ejemplo porque vas a hacer un require/include de ese archivo, o porque vas lees/escribir en esa ruta, el sistema tiene que resolver esa ruta: saber donde es exactamente, si es un directorio o un archivo, etc.

Para mejorar su rendimiento y minimizar lecturas de disco, PHP utiliza una caché interna donde guarda información sobre el sistema de archivos. No estoy hablando de Opcache, sino de otra caché llamada realpath_cache. Si intentas resolver la misma ruta dos veces seguidas, solo en la primera PHP le pedirá información al lentísimo sistema de archivos: la segunda se leerá directamente de la caché, mejorando mucho el rendimiento.

Esto es bueno, ¿no?

Sí, claro. El tema es que, como con todas las cachés del mundo, el problema viene a la hora de invalidar la caché y decirle que queremos utilizar contenido nuevo.

There are only two hard things in Computer Science: cache invalidation and naming things.

Cuando desplegamos código nuevo, el contenido de la ruta de nuestro Document Root cambia. Aunque en nuestro código siempre usemos la misma ruta para hacer algo, piensa por ejemplo la ruta relativa que usas para incluir el autoload, despues de cada deploy, esa ruta se resuelve a un lugar distinto en el disco, porque el enlace simbólico apunta a otro sitio. Esto evitará que veamos la versión nueva del código desplegado, hasta que esta caché no caduque o hagamos algo al respecto.

Cómo funciona Apache

A diferencia de Opcache, que se guarda en memoria compartida por todos los procesos, la realpath_cache es local para cada proceso del sistema. Este detalle es importante porque si utilizas Apache prefork para servir tu aplicación, cuando inicias Apache, este crea varios procesos hijos, tantos como le hayas configurado. Cada proceso hijo creado servirá X número de peticiones en su vida (esto también es configurable), y una vez que ha cumplido su deber, Apache lo matará y lo reemplazará con otro proceso hijo, poco a poco renovando todos los procesos que sirven páginas.

Es decir, no podemos preveer exactamente cuando los procesos dejarán de existir. Sumado a que la realpath_cache es local a cada proceso, la nueva versión que acabamos de desplegar se irá sirviendo aleatoriamente, dependiendo de qué proceso de Apache te haya asignado el servidor.

Como dijimos antes, podríamos solventarlo haciendo un reinicio de Apache despues de cada despliegue, pero dejaríamos de servir páginas el tiempo que tardase en reiniciar.

Mal, mal, mal, verdadera mal, por no deci borchenoso

Reiniciando elegantemente

Pero tranquilo, no sufras, hay solución. Apache nos ofrece una variante al reinicio, llamada graceful restart. Esta variante, en vez de matar al proceso de Apache y todos sus hijos para reiniciarlo, lo que hace es que el proceso padre revisa a los procesos hijos de forma que:

Si no están haciendo nada, los sustituye por un proceso nuevo.
Si está sirviendo una petición en este momento, cuando termine lo sustituye por un proceso nuevo.

Como dijimos que realpath_cache era local a cada proceso, cuando Apache levanta un nuevo proceso hijo la realpath_cache está vacía para ese proceso y las rutas se resolverán al código nuevo que acabamos de desplegar. Todo esto sin dejar de dar servicio, porque siempre hay procesos sirviendo páginas.

Pesao. Que yo venía aquí a solventar el problema de Opcache

Cierto. Opcache no es más que un diccionario (piensa en un array PHP), en el que cada key es la ruta del fichero compilado, y el value es el resultado de esa compilación. Cuando se va a ejecutar un fichero PHP, se ve si la ruta de ese archivo ya es una de las _keys_ en el diccionario, si ya lo está significa que ya lo hemos compilado antes, y se utiliza directamente el value. Si no, se compila y se guarda en el diccionario.

El ‘final plot twist’ de todo esto es que Opcache utiliza realpath_cache internamente para resolver la ruta de los ficheros. Por tanto, si hacemos un graceful restart después de cada despliegue, la ruta del archivo habrá cambiado, resuelve a una carpeta distinta, así que será como un fichero totalmente nuevo para Opcache y volverá a compilarlo, haciendo que sirvamos la versión nueva.

Conclusión

Lo que hemos visto hoy es tan solo uno de los posibles problemas a la hora de desplegar código. Otro problema, por ejemplo, sería el que se produce cuando iniciamos un despliegue, un visitante entra en la web, justo después se cambia el enlace simbólico y estamos sirviendo archivos estáticos como javascript o css. Es posible que algunos archivos hayan sido de la versión vieja, y otros de la versión nueva, llevando a posibles inconsistencias. Hay módulos de apache que intentan solventar este tipo de problemas.

El despliegue de código es un tema complicado y muy interesante. Últimamente está avanzando mucho con conceptos como servidores inmutables y los contenedores, pero eso ya es tema de otro post.

Jugando con conceptos de DDD

Wed, 29 Oct 2014 00:46:39 +0000

El pasado fin de semana se celebró en Barcelona una nueva edición de la Software Craftmanship, donde se hablaron de diversos temas relacionados con las buenas prácticas a la hora de crear software. Entre ellos, en mi opinión, hubo uno que pareció suscitar mayor interés en la gente y ocupó un papel protagonista en los dos días de conferencia: Domain Driven Design. Es un tema en el que creo que muchos estamos todavía aprendiendo, intentando dar sentido a la inmensa cantidad de conceptos e información que aparecen tanto en el libro azul como en el rojo.

En esta búsqueda de sentido, me surgió una duda que creo que no aparece resuelta directamente en ninguno de los dos libros, y que compartí con el resto de asistentes en una de las charlas sobre DDD. Quiero reproducirla otra vez aquí, para poder hablar un poco más sobre el tema. Creo que no hace falta mostrar código, pero realmente me gustaría vuestra opinión, así que si es necesario, decídmelo y añadiré código.

Creando value objects a partir de entidades

Mi duda viene a la hora de combinar dos de los objetos básicos de DDD: las entidades y los value objects. En todos los ejemplos que he visto, los value objects pueden ser simples objetos que no dependen de ningún otro, o que se construyan utilizando otros value objects. Por su parte, las entidades se construyen tradicionalmente sin dependencias, o utilizando algún value object. Mi pregunta es: ¿hay algo que nos impida construir value objects que dependan de entidades, que reciban entidades en su constructor?

Cuando lancé esta pregunta durante la sesión de DDD Táctico que impartía Christian, la mayoría de gente me miró como si fuese un loco (solo Carlos parecía encontrar sentido a mis palabras), pero dejadme explicar por qué creo que construir value objects con entidades puede ser perfectamente válido.

Un value object es un objeto el cual su identidad viene dada por el valor que contiene. No tiene un identificador como tal, porque su propio valor lo identifica. Dos value objects que contienen el mismo valor, son iguales.

Un ejemplo de caso de uso para mi pregunta podría ser cuando intentamos modelar una aplicación para votar en unas elecciones. Una práctica que suelo utilizar es la de intentar modelar todo el dominio con value objects, y solo “promocionar” el objeto a entidad cuando es estrictamente necesario. En este caso, si tenemos ciudadanos que votan, y partidos políticos que pueden ser votados, veo lógico que esos sean entidades, ya que un ciudadano puede hasta cambiarse el nombre y seguir siendo el mismo ciudadano. Tiene una identidad que lo identifica (valga la redundancia). Con el partido político pasa algo parecido: podría cambiar su logotipo, o hasta su nombre, y seguir siendo el mismo.

Pero para modelar los votos que la gente hace a los partidos, quise intentar hacerlo con un value object. Este value object debe contener qué ciudadano ha votado, a qué partido político, y quizá el momento exacto en el que ha votado. Si decíamos que tanto los ciudadanos como los partidos políticos son entidades… este objeto “voto” tendría que construirse a partir de entidades.

Inmutabilidad del value object

No recuerdo quién, argumentó que, por definición, los value objects son inmutables, y si un ciudadano se cambiase el nombre entonces el voto habría cambiado, perdiendo su inmutabilidad. Pero esto no es cierto. Precisamente, debido a que las entidades tienen identidad, la forma de decir si una entidad es o no igual a otra, es comparando los identificadores de esas entidades. Si un ciudadano se cambia el nombre, sigue siendo el mismo ciudadano. Por tanto, si un value object Voto contiene una entidad Ciudadano, y este ciudadano se cambia el nombre, el value object sigue sin haber mutado, ya que sigue conteniendo la misma entidad: la identidad del ciudadano es la misma.

Si cambiase el ciudadano que ha votado, o el partido político al que ha votado, sería otro voto. Es el valor del value object lo que le identifica. Es inmutable: yo no puedo coger la papeleta de un voto y tachar una cosa para poner otra.

Alguien podría preguntarme que por qué complicarme la vida y no hacer una entidad. Creo que modelar con value objects es más simple, manteniendo la inmutabilidad lo máximo posible. Estos votos podrían formar parte de una entidad de elecciones (o algo parecido), que sería lo que finalmente persistiría esos votos en base de datos. Cuantas menos entidades, más sencillo de programar y más sencillo de razonar. ¿Para qué añadir identidades a cosas que no las necesitan?

Ya sé que no es un ejemplo que aparezca en los libros, pero a mí es un diseño que a priori me cuadra. Solo lo he desarrollado en mi cabeza, así que no sé con qué problemas me podría encontrar. Como soy masoca, lo expongo aquí públicamente para que me lo crujáis.

¿Qué os parece?

Sácale todo el partido a los tests haciendo que griten

Sun, 26 Jan 2014 18:09:33 +0000

Si tuviese que decir en qué se basa una prueba unitaria, diría que las principales características que debe cumplir son (sin ningún orden en particular):

Que sea rápido y sin efectos secundarios.
Que sea realmente unitario.
Que sea auto explicativo.

Pero con el tiempo veo que la gente tiende a centrarse en las dos primeras de mi lista.

Se busca que sea rápido y sin efectos secundarios porque de esa forma podemos lanzarlos siempre que queramos, dándonos confianza. Si tuviésemos que esperar minutos en saber el resultado, o tuviésemos que andar limpiando una base de datos cada vez que quisiésemos lanzar pruebas, simplemente no lo haríamos tan frecuentemente como debiéramos.

También se prioriza que sean unitarios y aislados, para que cuando algo falle, tengamos la granularidad suficiente para identificar el problema en cuestión de segundos. Si tuviésemos una prueba que lo probase todo, el día que fallase, no sabríamos cual de las partes ha sido la culpable.

Y aunque considero que estas dos características son importantísimas, creo que se desprecia la última de mi lista. Las pruebas deberían ser auto explicativas, en el sentido de que debería ser muy fácil saber qué se está probando en todo momento, y sobretodo, qué hace el componente que estamos probando.

La mayoría del tiempo que programamos nos la pasamos leyendo código ya existente, intentando entender qué es lo que hace. Esto implica tener que leer las pruebas. Y no sé vosotros, pero yo me he encontrado con tests infumables.

Como mejorar la legibilidad de los tests

Voy a poner un ejemplo muy sencillo donde podemos aplicar una serie de mejoras. Quizá al ser tan simple se vea menos el efecto, pero aplicándolo a esos mastodontes que nos podemos encontrar en la vida real, creedme que mejoraremos mucho los tests.

El refactoring de extraer método no sirve para ahorrar líneas de código, si no para que el método sea más fácil de leer.

Primera aproximación: mocks en métodos privados

En el siguiente ejemplo, tenemos una clase encargada de identificar usuarios. Tiene dos colaboradores: el repositorio de usuarios para encontrar usuarios, y un codificador de contraseñas.

public function testShouldReturnAuthenticatedUserForValidCredentials()
{
    $email      = 'john@doe.com';
    $encoded_pass   = 'encoded_pass';
    $password           = 'decoded_pass';
    $user       = new User( $email, $encoded_pass );
    $user_repo  = $this->getMock( 'UserRepository' );
    $user_repo
    ->expect( $this->any() )
    ->method( 'findByEmail' )
    ->will( $this->returnValue( $user ) );

    $pass_encoder   = $this->getMock( 'PasswordEncoder' );
    $pass_encoder
    ->expect( $this->once() )
        ->method( 'hash' )
    ->with( $password )
    ->will( $this->returnValue( $encoded_pass ) );

    $auth_service   = new AuthService( $user_repo, $pass_encoder );

    $this->assertEquals(
    $user,
    $auth_service->authenticate( $email, $password ),
    'Must return the user when credentials are valid.'
    );
}

A pesar de que apenas hay lógica que testear, y gracias en parte a lo incómodo de PHPUnit (tenéis que probar PHPSpec, en serio), los tests empiezan a crecer, obligándonos a leer un montón de líneas cada vez que queramos entender qué hace esto.

Muchos programadores intentan solventar este problema extrayendo un método para, por ejemplo, la creación de mocks. Queda algo tal que así.

public function testShouldReturnAuthenticatedUserForValidCredentials()
{
    $email      = 'john@doe.com';
    $encoded_pass   = 'encoded_pass';
    $password   = 'decoded_pass';
    $user       = new User( $email, $encoded_pass );

    $this->createRepositoryMock( $email, $encoded_pass );
    $this->createEncoderMock( $password, $encoded_pass );

    $auth_service   = new AuthService( $user_repo, $pass_encoder );

    $this->assertEquals(
    $user,
    $auth_service->authenticate( $email, $password ),
    'Must return the user when credentials are valid.'
    );
}

private function createRepositoryMock( $email, $password )
{
    $user       = new User( $email, $password );
    $user_repo  = $this->getMock( 'UserRepository' );
    $user_repo
    ->expect( $this->any() )
    ->method( 'findByEmail' )
    ->will( $this->returnValue( $user ) );

    return $user_repo;
}

private function createEncoderMock( $password, $encoded_pass )
{
    $pass_encoder   = $this->getMock( 'PasswordEncoder' );
    $pass_encoder
    ->expect( $this->once() )
    ->method( 'hash' )
    ->with( $password )
    ->will( $this->returnValue( $encoded_pass ) );

    return $pass_encoder;
}

Aunque a priori pueda parecer que esto ha mejorado la legibilidad de nuestros tests, nada más lejos de la realidad. Lo único que hemos hecho es reducir el número de líneas del test, pero sigo teniendo que leerme todo cada vez que necesite entenderlo.

El refactoring de extraer método no sirve para ahorrar líneas, si no para que el método sea más fácil de leer. El nombre _createRepositoryMock()_ no me dice absolutamente nada sobre por qué lo estamos haciendo.

Un enfoque mejor

Si el objetivo es que se entienda mejor el código, ¿por qué no hace todo explícito? Vamos a hacer lo mismo, pero pensando en el por qué de las cosas.

public function testShouldReturnAuthenticatedUserForValidCredentials()
{
    $email      = 'john@doe.com';
    $encoded_pass   = 'encoded_pass';
    $password   = 'decoded_pass';
    $user       = $this->createExistingUser( $email, $encoded_password );
    $user_repo  = $this->createUserRepoWhenUserExists( $user );
    $pass_encoder   = $this->createEncoderWhenEncoderMustEncodePassword( $password, $encoded_pass );

    $auth_service   = new AuthService( $user_repo, $pass_encoder );

    $this->assertEquals(
    $user,
    $auth_service->authenticate( $email, $password ),
    'Must return the valid user when credentials are valid.'
    );
}

private function createUserRepoWhenUserExists( $user )
{
    $user_repo = $this->getMock( 'UserRepository' );
    $user_repo
    ->expect( $this->any() )
    ->method( 'findByEmail' )
    ->will( $this->returnValue( $user ) );

    return $user_repo;
}

private function createExistingUser( $email, $password )
{
    return new User( $email, $password );
}

private function createEncoderWhenEncoderMustEncodePassword( $password, $encoded_pass )
{
    $pass_encoder = $this->getMock( 'PasswordEncoder' );
    $pass_encoder
    ->expect( $this->once() )
    ->method( 'hash' )
    ->with( $password )
    ->will( $this->returnValue( $encoded_pass ) );

    return $pass_encoder;
}

Estos nombres no tienen por qué ser los mejores, pero la idea es esa: hacer explícito el motivo de todo, para que cuando volvamos a leer el código (o algún compañero nuestro), todo lo que está ocurriendo se entienda a la perfección.

Este primer enfoque es bastante básico, y si vemos que se complica, siempre podemos acudir a patrones de creación como el patrón builder o factories para los mocks.

Revelar la intención de nuestro código y el objetivo del test: lo más importante

Haciendo que el objetivo de cada línea sea revelar con claridad la intención de nuestro código y qué caso concreto estamos testeando en ese momento, reduciremos muchísimo el tiempo necesario para entenderlo. Da igual que ocupe más líneas, o que tarde dos microsegundos más en ejecutarse. Los objetivos de los tests son los que vimos al principio de este artículo, no son el rendimiento o tener menos líneas de código.

Luchando contra la duplicación

He visto desarrolladores que detectan que necesitarán un stub en todos los test cases, así que sacan la creación del stub al método de setUp, para ahorrar las líneas de configuración del stub.

Volvemos a lo mismo. Debemos preguntarnos si eso mejora la legibilidad del test. En mi opinión, normalmente no lo hace, porque _esconde_ una colaboración, que puede que pasemos por alto ya que está en el setUp y no en el test case.

“Pero entonces tendremos duplicación!”, me dirán los lectores más atentos. Pero yo no digo que dupliquemos, sino que lo hagamos explícito. Si vemos que por hacerlo explícito vamos a duplicar código, saquemos la duplicación a un método privado que contenga la lógica que se duplica, y llamemos a este método privado desde el test case. El nombre de ese método privado nos dirá el motivo de por qué está ese código ahí.

Conclusión

Nunca debemos olvidar que los tests son nuestra primera documentación. Es la mejor forma de ver cómo funciona un componente, cómo se configura, y qué valores debo esperar que devuelva. Cuando tengo que modificar código ya existente, entender qué es lo que hace es vital. Si no hago que mis tests GRITEN el comportamiento de mis clases, me estoy perdiendo otra de las grandes ventajas de los tests.

Administrar recursos frontend con Assetic (sin Symfony2)

Sun, 19 Jan 2014 18:12:29 +0000

Buscando mejorar el rendimiento de nuestras aplicaciones web, muchas veces nos centramos en el backend sin prestar suficiente atención al frontend. Una de las mejoras que podemos aplicar en la parte frontal de nuestras webs para que vayan más rápidas es reducir el número de peticiones HTTP que son necesarias para cargar la web. Para ello podemos, por ejemplo, combinar varios archivos CSS o JS en uno solo para que, aunque tengamos que cargar muchos recursos, solo una petición HTTP sea necesaria.

Hacer esto a mano puede ser tedioso y llevar a problemas, por tanto una buena solución sería preguntarnos si alguien ya ha solucionado este problema antes. Como tantas otras veces la respuesta es que sí.

Hoy vengo a hablaros de Assetic, una herramienta que nos permite administrar fácilmente los recursos de la web, como archivos CSS o Javascript, para combinarlos, minificarlos u optimizarlos.

El problema de Assetic es que, aunque encontrarás muchos ejemplos y artículos en internet, el 99% de ellos son utilizando Symfony2. Mi objetivo con este post es explicar assetic para que puedas utilizarlo en cualquier sitio, independientemente del framework elegido.

Vocabulario básico

Vamos a definir un vocabulario básico que nos puede ayudar cuando busquemos ayuda en internet o intentemos entender el funcionamiento de assetic:

Asset: Un recurso estático como un archivo CSS, un fichero Javascript o una imagen. Hay 2 clases que nos permitirán describir assets: FileAsset, que es un archivo normal; y GlobAsset, que representa un directorio que contiene varios archivos que queramos cargar.
Filter: Un filtro que transforma de alguna forma el contenido del fichero, como por ejemplo minificándolo, o traduciendo de SASS a CSS. Hay muchos filtros distintos.
AssetManager: Un administrador de los assets. Nos permitirá ponerle nombre, y crear grupos nombrando a otros assets declarados anteriormente. El asset al que le ponemos nombre puede ser un FileAsset, _GlobAsset_ o AssetCollection.
AssetCollection: Un conjunto de assets, es decir, varios _FileAsset_ o GlobAsset. Puede contener otras colecciones. El constructor acepta dos arrays, uno con los diferentes assets que componen el collection, y otro con el conjunto de _filters_ que aplicaremos.
FilterManager: Lo mismo que el _AssetManager_ pero para filtros.
AssetFactory: Una clase que nos facilitará el trabajo de conectar todo lo que hemos visto hasta ahora, pasándole un _AssetManager_ y un FilterManager.
Formulae: Lo que define a un asset: fichero/s y/o filtro/s utilizados para crearlo.
Dump: Generar el recurso especificado, pasándole los filters elegidos. Podemos utilizarlo para mostrar el contenido por pantalla de forma dinámica o para guardarlo en un fichero y servirlo de forma estática.

Instalación de Assetic

Podemos instalar assetic a través de composer.

Sirviendo contenido dinámicamente

Vamos a realizar un ejemplo básico en el que vamos a coger todos los ficheros javascript de nuestro proyecto y vamos a hacer que assetic los combine en uno solo y los sirva dinámicamente, es decir, el resultado de combinarlos no lo guardará en disco,sino que tendremos una URL en nuestra aplicación que generará el javascript combinado. Esa URL es la que utilizaríamos en nuestro HTML para incluir el javascript.

require_once __DIR__.'/../vendor/autoload.php';

use Assetic\Asset\AssetCollection;
use Assetic\Asset\GlobAsset;

$js = new AssetCollection(array(
 new GlobAsset( '/var/www/my_project/web/js/*' ),
));

// Vamos a mostrar código Javascript, por tanto
// debemos especificárselo al navegador con la cabecera correspondiente
header( 'Content-type: text/javascript' );

// Mostramos el código Javascript
echo $js->dump();

Es nuestra labor crear una página/controlador/sección con este código y una ruta de nuestra web apuntando hacia ahí. Si la visitamos, veremos por pantalla todo el código Javascript correspondiente a todos los archivos que había en la carpeta _/var/www/my_project/web/js/_ combinado en un solo archivo. Por tanto, en nuestro HTML podríamos cambiar todos los archivos javascript incluídos y dejar solo este, reduciendo el número de peticiones HTTP y mejorando la velocidad y rendimiento de la web.

No es obligatorio utilizar _AssetCollection_ para esto, ya que podríamos haber utilizado directamente un _FileAsset_ o GlobAsset, pero normalmente vamos a tener más de un archivo.

Si no queremos coger todos los archivos de una carpeta, sino solo algunos, tendríamos que hacer lo siguiente

require_once __DIR__.'/../vendor/autoload.php';

use Assetic\Asset\AssetCollection;
use Assetic\Asset\FileAsset;
use Assetic\Asset\GlobAsset;

$js = new AssetCollection(array(
 new FileAsset( '/var/www/my_project/web/js/main.js' ),
 new FileAsset( '/var/www/my_project/web/js/jquery.min.js' ),
 new GlobAsset( '/var/www/my_project/web/js/bootstrap/*' )
));
// Vamos a mostrar código Javascript, por tanto
// debemos especificárselo al navegador con la cabecera correspondiente
header( 'Content-type: text/javascript' );

// Mostramos el código Javascript
echo $js->dump();

Si os fijáis en el output del javascript combinado que genera este código, salvo que el JS estuviese minificado de antes, no estará minificado ahora. En el caso de haber tenido coffeescript, esto no nos lo hubiese compilado a javascript. Para hacer este tipo de tareas tenemos que utilizar los filtros.

Usando filtros

Los filtros nos van a permitir transformar el contenido de los asset que habíamos definido. Para definirlos tenemos distintos métodos. Podemos definir un determinado asset con un filtro específico si solo queremos que se aplique a ese en particular. Pero también podemos asignar filtros a un AssetCollection y que lo aplique a todos. Dependerá de qué es lo que queremos hacer.

En el siguiente ejemplo vamos a ver los dos casos. Un filtro particular para compilar de código LESS a CSS, y el compresor YUI para que minifique todos los assets de la colección.

require_once __DIR__.'/../vendor/autoload.php';

use Assetic\Asset\AssetCollection;
use Assetic\Asset\FileAsset;
use Assetic\Asset\GlobAsset;
use Assetic\Filter\LessFilter;
use Assetic\Filter\Yui;

$css = new AssetCollection(array(
    new FileAsset('/path/to/src/styles.less', array(new LessFilter())),
    new GlobAsset('/path/to/css/*'),
), array(
    new Yui\CssCompressorFilter('/path/to/yuicompressor.jar'),
));

header( 'Content-type: text/css' );
// this will echo CSS compiled by LESS and compressed by YUI
echo $css->dump();

Creando un controlador con el código anterior, y una ruta apuntando a él, podríamos ir a nuestro código HTML y cambiar todas las peticiones de CSS en una sola hacia dicha ruta.

La cantidad de filtros disponibles es enorme y salvo que quieras realizar algo extraño, encontrarás uno que hace lo que buscas. Recuerda que es probable que para utilizar estos filtros, tengas que instalar la herramienta en cuestión. Por ejemplo, para utilizar YUI como en mi ejemplo, tendrías que instalar YUI (en Ubuntu):

sudo apt-get install yui-compressor

Y el lugar de instalación es el que debes poner en el constructor del filtro, para que sepa donde está el _jar_ ejecutable.

Organizando mejor los recursos

Los ejemplos que hemos visto están bien, pero en un proyecto más grande tendrás muchos recursos css o js que quieras cargar y la cosa puede complicarse.

Assetic intenta hacernos la vida más fácil a través del _AssetManager_ y el FilterManager.

AssetManager

El _AssetManager_ es… bueno, eso, un administrador de assets. Básicamente podemos ponerle un nombre a cada asset definido. ¿Por qué es esto importante? Pues porque luego podemos hacer referencia a un asset definido con anterioridad, y el_AssetManager_ se encargará de que assetic no haga todo el trabajo sobre el mismo recurso dos veces.

Por ejemplo, si queremos cargar jQuery y además, un plugin de jQuery que necesita, obviamente, de jQuery.


use Assetic\Asset\AssetCollection;
use Assetic\Asset\FileAsset;
use Assetic\AssetManager;
use Assetic\Asset\AssetReference;

$jquery = new FileAsset( '/path/to/jquery.min.js' );

$am = new AssetManager();
$am->set( 'jquery', $jquery );

$plugin1 = new AssetCollection( array(
    new AssetReference( $am, 'jquery' ),
    new FileAsset( '/path/to/jquery.plugin.js' )
));

$plugin2 = new AssetCollection( array(
    new AssetReference( $am, 'jquery' ),
    new FileAsset( '/path/to/another/jquery.plugin.js' )
));

$js = new AssetCollection( array(
    $jquery,
    $plugin1,
    $plugin2
));
header( 'Content-type: text/javascript' );
echo $js->dump();

En el código anterior, aunque utilicemos jQuery varias veces, Assetic solo lo tratará una vez. Con este mecanismo podríamos generar distintos paquetes dependiendo de la sección de la web en la que estemos, cargando solo el Javascript necesario para esa sección, y assetic solo haría el trabajo una vez, aunque repitiésemos ficheros.

FilterManager

El _FilterManager_ es algo muy parecido al AssetManager, pero para filtros. Simplemente damos de alta los filtros que estarán disponibles a utilizar luego cuando creemos assets con el factory.

Igual que con el AssetManager, si Assetic detecta que vamos a aplicar el mismo filtro al mismo archivo, dos veces, solo lo hará una. Un poco abajo se ve el código necesario para utilizar el FilterManager.

AssetFactory

Para que todo esto sea más fácil de utilizar y no tengamos que andar creando y conectando todos estos objetos a mano, Assetic tiene una clase llamada AssetFactory para generar assets de forma sencilla.

require_once __DIR__.'/../vendor/autoload.php';

use Assetic\Asset\AssetFactory;
use Assetic\Asset\FilterManager;
use Assetic\Filter\Yui\CssCompressorFilter;
use Assetic\Filter\Yui\JsCompressorFilter;

$fm = new FilterManager();
$fm->set('yui_css',new CssCompressorFilter('/path/yuicompressor.jar'));
$fm->set('yui_js',new JsCompressorFilter('/path/yuicompressor.jar'));

$factory = new AssetFactory( '/path/doc_root' );
$factory->setAssetManager( new AssetManager() );
$factory->setFilterManager( $fm );

$css = $factory->createAsset(
    array(
        'css/style.css',
        'css/bootstrap/*.css', // css in "/path/doc_root/css/bootstrap"
), array(
        'yui_css' // filter through the filter manager's "yui_css"
));

header( 'Content-type: text/css' );
echo $css->dump();

La factory funciona de forma parecida a una AssetCollection, ya que le pasamos un array de assets y otro de filtros. Como se basa en un _AssetManager_ y en un FilterManager, todas las propiedades de estos se aplican al utilizar la factory.

Con respecto al FilterManager, fíjate que hemos creado dos filtros, aunque luego solo estamos utilizando uno en el factory, el filtro llamado “_yui_css_“.

Mejorando la velocidad: guardando en disco

Hasta aquí todo bien. El único problema es que cada vez que se visita la ruta correspondiente a un asset y se ejecuta la llamada al método dump(), tiene que leer el contenido del disco, juntarlo y aplicar los filtros elegidos. Esto hará que la web cargue más lenta, con lo cual nuestro objetivo inicial de mejorar el rendimiento se va al traste.

Pero no sufras: todo tiene solución. En vez de generarlo cada vez, podríamos generarlo solo una vez y guardarlo en disco para que en las siguientes peticiones se sirva estáticamente la versión generada.

Para ello, Assetic nos proporciona un _AssetWriter_ para escribir en el disco aquello que generemos.

require_once __DIR__.'/../vendor/autoload.php';

use Assetic\Asset\AssetFactory;
use Assetic\Asset\FilterManager;

$css = $factory->createAsset(
    array(
        'css/style.css',
        'css/bootstrap/*.css', // css in "/path/doc_root/css/bootstrap"
), array(
        'yui_css' // filter through the filter manager's "yui_css"
));

$writer = new AssetWriter( '/path/doc_root/generated' );
$writer->writeAsset( $css );

Tan solo le pedimos al writer que escriba en disco los assets que queramos. Si tenemos varios assets dentro de un AssetManager, también podemos pasarle un _AssetManager_ y que automáticamente escriba en disco todos los assets configurados en el manager. Lo normal suele ser escribirlos en una carpeta aparte de archivos “compilados” o “generados”, pero eso ya depende de como te quieras organizar.

De esta forma, no serviríamos css y js de forma dinámica como estábamos viendo hasta ahora, es decir, no tendríamos una ruta que generase “al vuelo” el contenido. Por el contrario, cargaríamos un archivo normal del disco, archivo que generamos mediante el último código visto. Este código podemos ponerlo en un script PHP de consola que ejecutaremos manualmente cada vez que queramos re-escribir en el disco nuestros recursos, como, por ejemplo, cuando hacemos deploy de nuestra aplicación.

El nombre que el fichero tendrá en el disco es generado automáticamente por Assetic, utilizando el hash SHA1, basándose en los assets, los filtros y las opciones elegidas, de tal forma que si esto varía, el SHA1 variará y el nombre del fichero sería distinto, por lo que tendríamos que volver a guardarlo en el disco.

Si no nos interesa este comportamiento, Assetic también nos deja elegir el nombre final del archivo, pasándoselo en un array de opciones al factory.

require_once __DIR__.'/../vendor/autoload.php';

use Assetic\Asset\AssetFactory;
use Assetic\Asset\FilterManager;

$css = $factory->createAsset(
    array(
        'css/style.css',
        'css/bootstrap/*.css', // css in "/path/doc_root/css/bootstrap"
), array(
        'yui_css' // filter through the filter manager's "yui_css"
), array(
        'output' => 'my_awesome_css.css'
));

$writer = new AssetWriter( '/path/doc_root/generated' );
$writer->writeAsset( $css );

Conclusión

Con esta introducción creo que queda más claro qué es qué dentro de Assetic, y cómo podríamos empezar a utilizarlo en una aplicación que no utilice Symfony2.

En el siguiente post sobre Assetic, veremos algunos conceptos más avanzados como su integración con Twig, o cache busting.

Inspección continua de la calidad de nuestro código

Tue, 05 Nov 2013 18:05:53 +0000

Una de las formas que tenemos para poder mejorar el código de nuestro proyecto es someterlo a una inspección continua y constante. Lo primero que podemos hacer es lanzar nuestros tests tras cada push al repositorio, de forma que sabremos en todo momento si hay algo que no funciona bien.

También podemos analizar la complejidad del código y comprobar si estamos incrementándola o disminuyéndola.

Hasta ahora, todas estas tareas eran posibles solamente teniendo un servidor de integración continua configurado, siendo Jenkins el más famoso. En él podemos ejecutar todas estas tareas tras cada push. Recursos como http://jenkins-php.org/ te ayudarán a configurar este versátil servidor hecho en Java.

La buena noticia es que cada vez hay más herramientas online que te permiten hacer estas tareas sin necesidad de configurar practicamente nada. Hoy veremos como lanzar tests y analizar la calidad de nuestro código sin utilizar un servidor de integración continua.

Ejecutando nuestros tests

Estos dos últimos años han sido la explosión en popularidad de TravisCI. TravisCI es un servicio que te permitirá lanzar tu suite de tests tras cada push. ¿Cómo? Pues cada vez que se envía código al repositorio, TravisCI levantará una máquina virtual y clonará tu código en ella. Una vez todo esté allí, ejecutará los tests y te dirá si algo se ha roto o todo sigue correcto.

También te permite ejecutar comandos antes de lanzar los tests, por si necesitas instalar dependencias de otras librerías o incluso programas en la máquina virtual.

Para que todo esto funcione, necesitas tener un archivo de configuración en tu repositorio que le diga a TravisCI qué es lo que tiene que hacer. Este archivo se llama _.travis.yml_ y un ejemplo podría ser este

language: php
php:
    - 5.3
    - 5.4
    - 5.5
before_install:
    - curl -s http://getcomposer.org/installer | php
    - php composer.phar --dev install

Con esta configuración le estamos diciendo a TravisCI que nuestro lenguaje es PHP, que queremos que lance los tests en 3 máquinas virtuales distintas, una con la versión 5.3 de PHP, otra con la 5.4 y otra con la 5.5. Además, antes de poder lanzar los tests, le decimos que instale las dependencias de nuestro proyecto mediante composer.

El hecho de saber si algo se ha roto con un commit es de vital importancia, sobretodo en proyectos con muchos programadores distintos, como los proyectos Open Source. Para esto, cada vez que hay un cambio de estado (alguien rompe los tests y pasamos de estable a roto, o viceversa), TravisCI nos enviará un email para tenernos informados.

Para que todo el mundo tenga visibilidad del estado actual, también pone a nuestra disposición una insignia que indica si los tests están en rojo o en verde. Podemos colocar esta insignia en el README.md de nuestro proyecto, y cualquiera que entre verá si hay algo roto.

Por último, recuerda que por defecto TravisCI ejecutará PHPUnit para lanzar los tests, utilizando la configuración del fichero _phpunit.xml.dist_ para saber donde están los tests y cómo lanzarlos. Si quieres cambiar algo de lo que TravisCI hace por defecto, la documentación está bastante bien.

Analizando la calidad del código

Existen un montón de herramientas de análisis estático de código PHP que nos dan todo tipo de información, desde si hay mucho copy/paste, hasta si nuestro código es poco abstracto. Son herramientas que puedes lanzar cuando quieras desde la consola, pero que como veíamos al principio del post, sería interesante lanzar cada vez que se envía código al repositorio. Si no queremos utilizar nuestro servidor de integración continua propio, una alternativa que tenemos es Scrutinizer.

Su funcionamiento es muy parecido al de TravisCI, pero en vez de lanzar tu suite de tests, lanzará todas las herramientas de análisis estático de código que hayas configurado. Para la configuración, tan solo debes modificar en la web de Scrutinizer el archivo de configuración, o tener un archivo _.scrutinizer.yml_ en tu repositorio. En la web puedes elegir una configuración global para todos tus proyectos, o tener una distinta para cada uno.

El mío tiene esta pinta

filter:
 excluded_paths: [vendor/*, app/*, web/*]

tools:
 php_cpd: true
 php_pdepend:
     excluded_dirs: [vendor]
 php_mess_detector: true
 php_analyzer: true
 php_loc:
     command: phploc
     excluded_dirs: [vendor]
     enabled: true

No tengo seleccionadas todas las herramientas, pero para hacer una prueba es suficiente con estas.

Una vez elegida tu configuración, puedes lanzar el análisis directamente eligiendo “_Schedule Inspection_” en la parte superior derecha. De todas formas, salvo que lo desactives en las opciones, cada vez que código nuevo se envíe al repositorio, se realizará una inspección de tu código.

Informes

Lo bueno es que después de ejecutarse, Scrutinizer genera unos informes muy bonitos con todo tipo de información útil.

Arriba de todo podemos ver la nota final de nuestro código, 9.18 en la imagen. Esta nota es calculada teniendo en cuenta el resultado de todas las inspecciones que tenemos configuradas. También nos ofrece un histórico con nuestra nota, o los incidentes (issues) de nuestro código que todavía tenemos pendientes por arreglar.

Por último, igual que TravisCI, nos ofrece la posibilidad de poner una insignia con nuestra nota en el README.md del repositorio, para que todo el mundo vea a simple vista la calidad del código.

Lo tienes fácil

Antigüamente tenías que pelearte con un servidor tipo Jenkins si querías tener funcionalidades de integración continua, pero cada vez salen más herramientas online a la luz que nos ayudan con la calidad de nuestro código. Todavía no tenemos todo lo que un Jenkins nos puede ofrecer, pero con estos dos simples servicios que hemos visto hoy, ya tendríamos mucho ganado.

Geolocalización en PHP y las páginas de afiliados locales

Sat, 02 Nov 2013 18:11:01 +0000

Una de las webs de las que soy responsable contiene artículos sobre productos electrónicos: análisis, comparativas, novedades, etc. Utilizando el sistema de afiliados de Amazon y, si tus análisis convencen a los usuarios para rascarse el bolsillo, puedes sacar un porcentaje de la venta.

El problema con Amazon es que tiene una tienda distinta para cada país. Es decir, Amazon para España no es el mismo que para Francia o Estados Unidos. El catálogo es distinto, sus usuarios diferentes y hasta el programa de afiliados funciona de manera distinta. De hecho, para participar en el programa de afiliados tienes que darte de alta por separado en cada uno de los países que quieras participar.

Mientras hacíamos esto, mi compañero y yo nos dimos cuenta de un detalle. Si un usuario desde México lee nuestro análisis y quiere comprarse el producto, seguramente lo quiera comprar en la tienda de Estados Unidos, no en la Española. Sin embargo, tener que poner en todos nuestros artículos varias versiones de enlaces del tipo “_si vienes desde México entra aquí, si vienes desde España entra allí_“, no nos parecía una opción viable. Así que, ¿cómo podíamos solventar esto?

Intentando traducir los enlaces “al vuelo”

Al principio pensé en crear un script en Javascript que al terminar de cargar la página cambiase todos los enlaces de la página, _traduciéndolos_ a la tienda del país local del visitante. Pero como decía antes, los catálogos no son iguales y los enlaces de Amazon no se pueden traducir tan fácilmente. Hay un plugin de WordPress que hace esto, pero parece que falla más que una escopeta de feria.

Sistema de enlaces propio

Así que finalmente opté por crear mi propio sistema de enlaces geolocalizados. ¿Qué es esto? Pues básicamente se trata de no utilizar los enlaces de tu sistema de afiliados, sino de utilizar unos enlaces propios que yo mismo genero y que redirigirán a la tienda local dependiendo del país del visitante.

Para ello, a partir de ahora en mis artículos no utilizaré el link de Amazon sino unos enlaces bajo mi propio dominio, como por ejemplo

Cuando un usuario visite esos enlaces, mi sistema hará dos cosas

Detectar el país del visitante
Basándonos en el país y el producto visitado, redirigir al usuario a la tienda correcta

Detectando el país del visitante

Para geolocalizar al usuario he utilizado la librería Geocoder que está lista para utilizar en los principales frameworks como Symfony o Laravel, así como un port a Javascript.

Es una librería muy completa ya que te permite configurar completamente el mecanismo que se utilizará para geolocalizar. Aunque la documentación no es perfecta, da mucha información sobre todas las posibilidades que ofrece.

Lo más básico que necesitas saber si quieres usarla, es que necesitas un proveedor de geolocalización y un adaptador para hablar con ese proveedor. Hay muchísimos proveedores. Desde FreeGeoIP, hasta Google Maps, pasando por GeoIP. Para utilizar estos proveedores necesitas un adaptador que lo ejecute, que puede ser desde un simple curl hasta librerías como Buzz o Guzzle.

En mi caso, quería lo más sencillo posible, así que opté por utilizar FreeGeoIP a través de curl. Para eso utilicé este código

$adapter     = new Geocoder\HttpAdapter\CurlHttpAdapter();
$provider    = new Geocoder\Provider\FreeGeoIpProvider( $adapter );
$geocoder    = new Geocoder\Geocoder();
$geocoder->registerProvider( $provider );

Con esto ya tenemos un objeto que dados unos datos del usuario, nos puede dar información sobre la posición de éste

$result = $geocoder->geocode('88.188.221.14');
// Result is:
// "latitude"       => string(9) "47.901428"
// "longitude"      => string(8) "1.904960"
// "bounds"         => array(4) {
//     "south" => string(9) "47.813320"
//     "west"  => string(8) "1.809770"
//     "north" => string(9) "47.960220"
//     "east"  => string(8) "1.993860"
// }
// "country"        => string(6) "France"
// "countryCode"    => string(2) "FR"
// "timezone"       => string(6) "Europe/Paris"

Redirigiendo a la tienda local

Ahora que podemos saber el país del visitante, tan solo tenemos que coger de un diccionario cual es el enlace que nos interesa. Además del país del usuario, el otro dato que usaremos en nuestro diccionario, es el producto en cuestión. Esto podemos obtenerlo a través de la URL de nuestro sistema de enlaces.

Utilizando los enlaces de ejemplo que puse más arriba, si el usuario entrase desde España en www.example.com/products/ipad-mini, yo le redireccionaré a la página del iPad Mini de la tienda española.

Para trabajar con la URL de forma segura, así como para conseguir la IP del usuario de forma fácil, he decidido utilizar el componente HttpFoundation de Symfony. Esta librería también me permite realizar cómodamente la redirección 302 a la tienda local.

La gestión del diccionario puedes hacerla con un simple array en el mismo archivo PHP, o mediante algún archivo de configuración como YAML o XML. Si el catálogo de productos fuese muy extenso, habría que realizar un backend para poder administrarlo, pero de momento es pequeño y manejable.

Para conseguir que todas las peticiones a esos enlaces se procesen a través del script que estamos creando, tendrás que cambiar tu virtual host. En Apache sería añadir algo parecido a esto

<Directory /var/www/project/products/>
        <IfModule mod_rewrite.c>
            RewriteEngine On
            RewriteCond %{REQUEST_FILENAME} !-f
            RewriteCond %{REQUEST_FILENAME} !-d
            RewriteRule . /products/index.php [L]
        </IfModule>
</Directory>

Conclusión

Con este mecanismo, tengo totalmente centralizado el sistema de enlaces de mi programa de afiliados. Además del beneficio que yo buscaba de poder utilizar la tienda local del usuario, en vez de siempre la misma, hay otro bastante interesante. Si yo quisiera cambiar de tienda, y en vez de utilizar Amazon utilizar otro proveedor, no tendría que cambiar todos mis artículos y anuncios, tan solo el diccionario del sistema de enlaces.

Nosotros en nuestra web tenemos la política de enlazar a la tienda con el precio más barato para el usuario, sin importar que esa tienda no nos de un porcentaje por la venta. Con este mecanismo, todo se ha vuelto mucho más fácil, porque si hay cambios en los precios tan solo tenemos que cambiar una línea en el diccionario.

Podéis ver el código de todo este sistema en mi cuenta de Github.

Herramientas para el programador PHP moderno

Fri, 18 Oct 2013 23:47:55 +0000

La comunidad de PHP ha evolucionado muchísimo en los últimos años, no pareciéndose en nada a las versiones anteriores. No solo ha cambiado mucho, si no que cada vez cambia más frecuentemente. Y cuando hablo de comunidad, me refiero tanto al lenguaje, como a las personas que lo utilizan, así como a las herramientas que nacen alrededor.

Hoy vengo a hablaros precisamente de herramientas. No puede ser que programes PHP con las mismas herramientas que utilizabas hace 3 años. Haber actualizado tu IDE a la última versión es un comienzo, pero no es suficiente. Estás perdiendo la posibilidad de trabajar más cómodamente y ser más productivo, pudiéndote centrar en lo que realmente importa: crear cosas.

De entre todas las herramientas que han nacido en los últimos años, voy a hacer hincapié en las que para mí son las más útiles, y ya no podría vivir sin ellas.

Estas herramientas son:

Boris

Cuando empecé a aprender Python, una de las cosas que más me sorprendió fue que para dar los primeros pasos con el lenguaje, no había que crear nuevos ficheros y ejecutarlos. Sencillamente ibas a un intérprete por línea de comandos y programabas directamente allí. Adiós complicaciones de cómo ejecutar lo que acabas de escribir en otro fichero, o de como incluir el fichero A en el fichero B. Todo eso fuera para poder centrarte en lo que realmente quieres: aprender el lenguaje.

Este intérprete se conoce comúnmente como un REPL: Read-Eval-Print-Loop . PHP trae por defecto con un modo interactivo para poder lanzar comandos, que puedes utilizar así

php -aInteractive shellphp > 1 + 3;php > var_dump( 1 + 3 );int(4)php > function plusTwo( $number ){php {php { return $number + 2;php { }php > echo plusTwo( 3 );5php >

pero es bastante limitado. No printa automáticamente el resultado de las expresiones ejecutadas, por tanto tienes que manualmente hacer echo’s ovar_dumps. Además, si se produce un fatal error, el modo interactivo terminará y perderás el estado actual. Esto no ocurriría con Boris . Os dejo el gif con la demo de Boris , porque una imagen vale más que mil palabras (sobretodo si es animada):

LadyBug

Calidad que sale desde nuestro país. Raúl Fraile se ha currado un sustituto para el var_dump() nativo de PHP que te dejará ojiplático. Se llama LadyBug y después de verlo te preguntarás cómo has sido capaz de interpretar el output del var_dump de PHP sin quedarte ciego. Para utilizarlo solo tienes que instalarlo via Composer, y utilizar la función ladybug_dump() en vez de var_dump() cuando quieras mostrar el valor de algo por pantalla. En su página de Github hay bastantes ejemplos de cual sería el output por pantalla, pero quiero poner uno aquí mismo:

Eso es el output cuando quieres pintar un objeto por pantalla y ver qué contiene. Fíjate que además de ponerte el contenido de las propiedades del objeto, como hace var_dump(), te muestra información de la clase del objeto, como donde está definida, constantes de clase e incluso los métodos y su visibilidad mediante unos iconos. Todo esto está genial, pero queda a la sombra de lo que me hubiese ahorrado horas de búsqueda en mis años iniciales con PHP: te dice en qué línea has llamado a la función ladybug_dump(). ¿Quién no se ha pasado un buen rato buscando dónde habías puesto el var_dump()? ¿Nadie? ¿Solo yo? Ok, vale.

Composer

Si todavía no lo conoces es que has vivido debajo de una piedra los últimos 2 años. No me extenderé mucho: solo utilízalo. En serio. Aquí tienes la documentación .

Bonus track: Vagrant y Puphet

Vagrant no es una herramienta para PHP específicamente, pero en el mundo de muchos gigas de RAM en el que vivimos, trabajar con máquinas virtuales locales se está convirtiendo en un standard. El hecho de que con un simple archivo de configuración puedas tener el mismo entorno que tu compañero, es increíble.

Hace 2 años que hice el curso sobre Puppet , y aunque no considero que haya sido perder el tiempo ni mucho menos, gracias a herramientas como Puphet , cada vez es menos necesario saber las entrañas de muchas cosas. Puphet es una abstracción de Puppet orientada a entornos PHP, de tal forma que como si un catálogo se tratase, vas eligiendo las tecnologías y configuraciones que quieres que tenga tu entorno de desarrollo. Con un par de clicks puedes elegir todo lo que necesites. Esto generará un archivo de configuración que será leído por Vagrant para moldear tu máquina virtual. Así de simple. Olvídate de como se instalan y configuran un montón de cosas: un par de clicks y listo. Si quieres cosas más avanzadas, tendrás que saber cómo funcionan, pero para el desarrollador PHP medio, esto es más que suficiente.

Conclusión

Además de estas herramientas, no olvides utilizar un IDE que te sea cómodo, y si no has probado PHPStorm , te lo recomiendo.

Así que ya sabes: utiliza Puphet y asegúrate de crear una máquina virtual que contenga composer, ladybug y boris, y fabrícate el entorno de desarrollo perfecto. No puedes programar igual que lo hacías hace 3 o 5 años. Esto va demasiado rápido como para permitírtelo.

Y tú, ¿usas alguna herramienta interesante?

Detectando tests dependientes con PHPUnit

Thu, 03 Oct 2013 18:07:55 +0000

A día de hoy, PHPUnit es el standard _de facto_ para escribir pruebas unitarias en PHP. En estas pruebas unitarias, intentamos que los tests sean totalmente aislados, es decir, que no tengan efectos secundarios, que no se conecten a servicios como API’s o bases de datos, y que no dependan unos de otros.

Sin embargo, cuando estamos escribiendo tests de integración para comprobar que ciertas clases se comunican correctamente entre ellas, o con otros servicios (base de datos, API’s, etc), los tests dejan de ser aislados, porque esa conexión es precisamente lo que queremos probar. Además, puede que tengan efectos secundarios porque, siguiendo con el ejemplo de la base de datos, vamos a comprobar si se han escrito datos correctos o si se han actualizado como deberían.

Lo que sí vamos a querer mantener, salvo que realmente nos haga falta lo contrario, es que los tests no sean dependientes entre sí. Es decir, que el orden en el que se ejecutan sea importante. No queremos que para que el testB() pase en verde, deba ejecutarse siempre después del testA(), y si esto no ocurre el test falle. Esto podría pasar por ejemplo cuando en el testB() leemos de base de datos algo que estamos insertando en el testA(). Si los cambiamos de orden, el testB() no encontrará los registros, y el test fallará irremediablemente.

Si conseguimos que los tests no compartan estados y que sean independientes, evitaremos que cuando alguien cambie el orden de los tests estos empiecen a fallar de forma aleatoria. En la vida real, sin embargo, estamos resolviendo problemas complejos y podríamos meter la pata. El problema es que cuando la cantidad de código que tienes empieza a ser muy grande, se hace complicado saber si alguien ha metido la pata en algún test y lo ha hecho dependiente de otro.

Para solucionar esto, he creado una librería que podéis utilizar para lanzar los tests de PHPUnit de forma aleatoria. Es decir, los test cases dentro de una clase de test se ejecutarán en un orden aleatorio, y si alguno dependía de la acción de otro, fallará y se pondrá de manifiesto que tiene que arreglarse.

PHPUnit ya ofrece una opción para que cada test case se lance en un proceso de php independiente, llamada process-isolation, pero esto provoca que los tests tarden mucho en ejecutarse, y cuando el número es elevado, el tiempo de espera se hace demasiado.

La idea con mi librería es no tener que modificar código de PHPUnit para que podamos seguir actualizando el framework sin miedo a perder cambios. Por tanto todo son clases nuevas y hasta un ejecutable nuevo, que nos evita tocar nada de PHPUnit.

PHPUnit nos ofrece una serie de mecanismos para añadir o cambiar funcionalidad existente del framework, pero realmente son una mierda (por lo menos en su versión actual 3.7). Nos permite extender clases para sobrescribir comportamiento, pero no da un mecanismo fácil (por configuración, por ejemplo) para decirle que utilice las nuevas clases que acabamos de crear. Debido a esto, la solución final implica que haya que utilizar un nuevo ejecutable incluído en mi librería llamado phpunit-randomizer, en vez del phpunit que viene por defecto con el framework.

Podéis coger la librería PHPUnitRandomizer en github.