Reference Guide to rampage-php¶

Installation / Application Setup¶

At first we’ll define the dependencies of our application. By now we only need to add rampage-php/framework as only dependency. This already defines dependencies to the essential zf2 components (i.e. zend-mvc):

php composer.phar require rampage-php/framework

This command will add the dependency to your composer.json. For more information on the composer.json package file see the Composer Documentation.

After doing so, we can run the install command to download all dependencies and generate the autoload files:

php composer.phar install

After executing this command, there will be a vendor directory containing all dependencies. To use them, all you need to do is to include vendor/autoload.php and all dependency classes become available to you.

Creating A Skeleton¶

After doing the composer magic, we only have the vendor dir. But now we want to create an application skeleton to start with. To simplify things, rampage comes with a tool to do so, a script called rampage-app-skeleton.php

Since rampage-php enhances zf2, it uses the zf2 layout. That means all modules are basically namespaces. In vanilla ZF2, you can only use the first namespace segment as module name which is quite limiting. Usually the first segment is the vendor name. But rampage-php enhances this behavior and adds the ability to use subnamespaces as well and map them to a dot-separated directory name.

Let’s assume your application module should be namespaced acme\myapp. Now let’s create the application layout with this modulename:

php vendor/bin/rampage-app-skeleton.php create acme.myapp

For windows this command should be:

.\vendor\bin\rampage-app-skeleton.php create acme.myapp

This will create:

• a public directory which will contain the webserver root.
• an application directory containing the application components
• the module skeleton for your application located in application/modules/acme.myapp

Defining Module Resources¶

Defining module resources is pretty easy. You just need to add them to your zf2 module config:

class Module
{
    public function getConfig()
    {
        return [
            // ...
            'rampage' => [
                'resources' => [
                    // Minimal, define only the base directory:
                    'foo.bar' => __DIR__ . '/resources',

                    // More detailed, allows to define additional resource types:
                    'foo.baz' => [
                        'base' => __DIR__ . '/resources',
                        'xml' => __DIR__ . '/resources/xml',
                    ],
                ]
            ]
        ];
    }
}

If you’re using the manifest.xml for your modules, you can define them in the resources tag:

<manifest xmlns="http://www.linux-rampage.org/ModuleManifest" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.linux-rampage.org/ModuleManifest http://www.linux-rampage.org/ModuleManifest ">
        <resources>
            <paths>
                <path scope="foo.bar" path="resource" />
                <path scope="foo.baz" path="resource" />
                <path scope="foo.baz" type="xml" path="resource/xml" />
            </paths>
        </resources>
</manifest>

Accessing Resources In Views¶

To access resources in views, you can use the resourceurl helper. The argument passed to this helper is the relative file path prefixed with @ and the scope like this: @scope/file/path.css.

Paths without the @ prefix will be searched in the current theme hierarchy directly. No attempt will be made to find them in a resource location.

Example:

<img src="<?php echo $this->resourceUrl('@my.module/images/foo.gif') ?>" />

Addressing Templates¶

Templates will also be populated by the resource locator. You can address them the same way as resources in view scripts like this: @scope/templatepath.

Example:

$viewModel = new ViewModel();
$viewModel->setTemplate('my.module/some/template');

Static Resource Publishing¶

There is also a way to publish resources to the public directory for static delivery. This is useful for production environments, where performance is important.

There are two ways to do this:

1. Use The Publishing Controller
2. Implement/Modify The Publishing Strategy

// module.config.php
return [
    'console' => [
        'router' => [
            'routes' => [
                'publish-resources' => \rampage\core\controllers\ResourcesController::getConsoleRouteConfig(),
            ]
        ]
    ],
];

return [
    'console' => [
        'router' => [
            'routes' => [
                'publish-resources' => [
                    'options' => [
                        'route' => 'publish resources',
                        'defaults' => [
                            'controller' => 'rampage\\core\\controllers\\ResourcesController',
                            'action' => 'publish'
                        ]
                    ]
                ]
            ]
        ]
    ]
];

Special Controllers/Routes¶

When implementing an authentication strategy which protects all of your routes from unauthorized access, you should be aware that the resource publishing strategy uses a ZF2 route/controller to publish static resources from your vendor or module directories.

The controller class is rampage\core\controllers\ResourcesController and it is registerd as rampage.cli.resources in the controller manager. The route for this controller is called rampage.core.resources.

If you do not allow this route/controller, public resources from your modules may not be served.

Defining Themes¶

Themes can be defined in your ZF2 module (or application) configuration as follows:

namespace my\component;

class Module
{
    public function getConfig()
    {
        return [
            'rampage' => [
                'themes' => [
                    'my.theme.name' => [
                        // Simple path definition following the default layout
                        'path' => __DIR__ . '/../theme',
                        'fallbacks' = [ 'parent.theme', rampage\core\resources\Theme::DEFAULT_THEME ],
                    ],

                    'my.other.theme.name' => [
                        // More detailed path definition
                        'path' => [
                            'base' => __DIR__ . '/../theme',
                            'template' => __DIR__ . '/../theme/templates',
                        ],
                        'fallbacks' = [ 'my.theme.name', 'parent.theme', rampage\core\resources\Theme::DEFAULT_THEME ],
                    ]

                ]
            ]
        ];
    }
}

One module may define multiple themes if needed.

Using The Theme¶

The current theme can be set either via calling the setCurrentTheme() method on the theme instance or by defining the default theme in the config.

If no theme is set explicitly and no default theme is defined, the current theme will be set to Theme::DEFAULT_THEME.

Defining the theme programmatically:

$serviceManager->get('rampage.theme')->setCurrentTheme('my.theme.name');

Defining the theme via config:

return [
    'rampage' => [
        'default_theme' => 'my.theme.name',
    ]
];

Theme Directory Layout¶

Within the defined theme directory, there should be two directories.

• public Which contains all public assets
• template Which contains template files

Overwriting Module Resources¶

Of course it is possible to overwrite module resources, like templates or public assets, in a theme. To do so simply place the file ine a directory named like the module’s resource name (See Defining Module Resources for details).

Example:

• theme directory

  • public

    • module.resource.name

      • some/public/file.css

  • template

    • module.resource.name

      • some/template.phtml
      • some-other-template.phtml

FilesystemInterface¶

Interface: rampage\\filesystem\\FilesystemInterface

This interface defines basic filesystem access via the ArrayAccess and RecursiveIterator patterns. It encapsulates the underlying filesystem and provides container like access. Much like Phar or ZipArchive

It is not intended to provide write access.

The following classes are provided as implementation for this interface:

• LocalFilesystem: For fs access on disk.
• GridFS: For accessing a MongoDB GridFS.

WritableFilesystemInterface¶

Interface: rampage\\filesystem\\WritableFilesystemInterface

This interface enhances the FilesystemInterface by defining write capabilities which are:

• adding files
• deleting files
• creating directories
• updating the access/modified timestamps (touch)

An implementation must provide these methods and respond gracefully, when they’re not supported (i.e. creating directories).

The following classes are provided as implementation for this interface:

• WritableLocalFilesystem: for fs access on disk.
• WritableGridFS: For accessing a MongoDB GridFS.

Available Implementations¶