CocurBuildBundle

Static site generator bundle for Symfony2. Early development release.

Table of Contents

1. Motivation
2. Installation
3. Configuration
   1. Generators
      1. File Generator
      2. Directory Generator
      3. JSON Generator
      4. CSV Generator
      5. YAML Generator
      6. Front-matter Generator
4. Usage
5. Author
6. License

Motivation

The documentation for BraincraftedBootstrapBundle is a Symfony2 project, because it is used to test and demonstrate the bundles features. I no longer wanted to maintain (and pay for) another Symfony2 project on my server and instead move it to Github Pages. CocurBuildBundle creates static HTML pages from Symfony2 controllers.

Installation

You can install CocurBuildBundle using Composer. Add to your composer.json:

{
    "require": {
        "cocur/build-bundle": "dev-master"
    }
}

You also have to add the bundle to your AppKernel.php:

// app/AppKernel.php

class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new Cocur\Bundle\BuildBundle\CocurBuildBundle(),
        );

        // ...

        return $bundles;
    }

    // ...
}

Configuration

• enable_assetic: When this option is true the assetic:dump command is executed when building the site. If the option is not defined it will be activated if AsseticBundle is installed.
• build_directory: The directory where the built site is saved.
• base_url: The base URL of the static site. Useful when the HTML is not saved in the root directory. Most commands have an option to override this on an individual basis.
• index_name: If a route doesn't contain a filename this value is appended to the route. The default value is index.html.

The default configuration looks like this:

# app/config/config.yml
cocur_build:
    build_directory: "%kernel.root_dir%/../build/site"
    base_url: ''
    index_name: index.html
    generators: ~

Generators

If an action requires parameters you can use generators to load the parameters from various sources. The bundle comes with four default generators:

• File generator: Every line in a file is a parameter; can only be used with actions that require a single parameter
• Directory generator: The name of every file or directory in a given directory is a parameter; can only be used with actions that require a single parameter
• JSON generator: A file that contains an array of objects; each object represents the parameters for an action; can be used with actions that require multiple parameters
• CSV generator: A file where each row contains the parameters of an action; must contain a header row that includes the parameter names; can be used for actions that require multiple parameters

Generators can be configured in your apps config.yml on a per-route basis.

File Generator

Parameters are generated from a file.

Required options:

• filename
• parameter

In the following example we have a route acme_demo_page with the path /p/{page} and we want to generate the page parameter from a file called data.txt.

# app/config/config.yml

cocur_build:
    generators:
        page:
            route: acme_demo_page
            generator: cocur_build.file_generator
            options:
                filename: "%kernel.root_dir%/../data.txt"
                parameter: page

We require now the data.txt file that contains one parameter per line.

products
about
contact

CocurBuildBundle will render the following pages:

• /p/products
• /p/about
• /p/contact

Directory Generator

Parameters are generated from the names of files in a directory.

Required options:

• directory_name
• parameter

In this example we have a route acme_demo_article with the path /article/{slug} and we want to render the page for every file in a directory.

# app/config/config.yml

cocur_build:
    generators:
        article:
            route: acme_demo_article
            generator: cocur_build.directory_generator
            options:
                directory_name: "%kernel.root_dir%/../articles"
                parameter: slug

The directory articles/ contains the following files:

articles/
    ⊢ 2013-12-03-bootstrap-bundle-2-0.md
    ⊢ 2013-12-04-cocur-bundle-0-1.md

CocurBuildBundle will render the following pages:

• article/2013-12-03-bootstrap-bundle-2-0
• article/2013-12-04-cocur-bundle-0-1

JSON Generator

Parameters are generated from a JSON file.

Required options:

• filename

Optional options:

• parameters: Only use these parameters to generate pages

Let's consider a route acme_demo_categorypage with the path /page/{category}/{page}. We require two parameters category and page that we want to generate from a JSON file called data.json.

# app/config/config.yml

cocur_build:
    generators:
        categorypage:
            route: acme_demo_categorypage
            generator: cocur_build.json_generator
            options:
                filename: "%kernel.root_dir%/../data.json"

The JSON file data.json has to contain an array where each element is an object with a category and a page property:

[
    { "category": "foo", "page": "bar" },
    { "category": "foo", "page": "baz" }
]

CocurBuildBundle will render the following pages:

• /pages/foo/bar
• /pages/foo/baz

CSV Generator

Parameters are generated from a CSV file.

Required options:

• filename

Optional options:

• delimiter (default value is ,)
• enclosure (default value is ")
• escape (default value is \)
• parameters: Only use these parameters to generate pages

Now we want to render the route acme_demo_person with the pattern /person/{name}/{age}/{city} using a CSV file persons.csv.

# app/config/config.yml

cocur_build:
    generators:
        person:
            route: acme_demo_person
            generator: cocur_build.csv_generator
            options:
                filename: "%kernel.root_dir%/../persons.csv"

The CSV file has to contain three columns and a header row containing name, age and city.

"name", "age", "city"
"Florian", "27", "Vienna"
"Daniela", "22", "Vienna"

CocurBuildBundle will render the following pages:

• /person/Florian/27/Vienna
• /person/Daniela/22/Vienna

YAML Generator

Parameters are generated from a YAML file.

Required options:

• filename

Optional options:

• parameters: Only use these parameters to generate pages

If we want to render the route acme_demo_person with the pattern /person/{name}/{age}/{city} we can also use a YAML file persons.yaml.

# app/config/config.yml

cocur_build:
    generators:
        person:
            route: acme_demo_person
            generator: cocur_build.yaml_generator
            options:
                filename: "%kernel.root_dir%/../persons.yml"

The YAML file persons.yml has to contain a list element for every person with a named property for every parameter.

-
    name: Florian
    age: 27
    city: Vienna
-
    name: Daniela
    age: 22
    city: Vienna

CocurBuildBundle will render the following pages:

• /person/Florian/27/Vienna
• /person/Daniela/22/Vienna

Front-matter Generator

Parameters are generated from the front-matter of files in a directory.

Required options:

• directory_name

Optional options:

• parameters: Only use these parameters to generate pages

In this example we have a route acme_demo_article with the path /article/{category}/{slug} and we want to render the page for every file in a directory.

# app/config/config.yml

cocur_build:
    generators:
        article:
            route: acme_demo_article
            generator: cocur_build.front_matter_generator
            options:
                directory_name: "%kernel.root_dir%/../articles"

For example, the file articles/2013-12-03-bootstrap-bundle-2-0.md could look like:

---
category: dev
slug: bootstrap-bundle-2-0
---
This is the rest of the file. Just some text.

CocurBuildBundle will render the following page:

• article/dev/bootstrap-bundle-2-0

Usage

The build command is the main command offered by CocurBuildBundle. It renders all pages and dumps the assets into the build directory.

$ php app/console cocur:build

The HTML code will be saved in the directory configured with cocur_build.build_directory.

Note: CocurBuildBundle can handle actions with parameters if a generator is configured for these routes.

When you use the build command, CocurBuildBundle uses the Symfony2 kernel to simulate a request to a page. The kernel is booted in the environment the command is invoked. If you want to build the pages for production, you need to build them in the prod environment.

$ php app/console cocur:build -e prod

If cocur:build is called in the prod environment the cache is cleared before the rendering.

You can remove all files from the build directory by using the clean command

$ php app/console cocur:clean

Author

• Florian Eckerstorfer (Twitter, App.net)

License

This bundle is licensed under the MIT license. For more information see the LICENSE file.