Installing

Table of Contents

1. Requirements
2. Installing
   1. Libraries
3. Server Config
   1. PHP Built-in Web Server Config
   2. Apache Config
   3. Nginx Config
   4. Caddy Config
4. Routes
5. Views
6. Renaming Project
7. Console Commands
8. Environment Variables
9. Versioning

Requirements

• PHP ≥ 7.3.0
• OpenSSL
• mbstring

Note: If you're a FreeBSD user, you'll also need to make sure the ctype, dom, filter, hash, json, phar, session, tokenizer, and xml extensions are installed.

Installing

Opulence can be easily installed using Composer:

composer create-project opulence/project --prefer-dist

Be sure to configure your server to finish the installation. Load up your website in a browser, and you should see a basic website explaining on how to start customizing it. That's it! If it does not show up, make sure you've made PATH_TO_OPULENCE/tmp writable.

Note: You can download Composer from here.

Libraries

Opulence is broken into various libraries, each of which can be installed individually:

• opulence/authentication
• opulence/authorization
• opulence/cache
• opulence/collections
• opulence/console
• opulence/cryptography
• opulence/databases
• opulence/debug
• opulence/environments
• opulence/events
• opulence/http
• opulence/io
• opulence/ioc
• opulence/memcached
• opulence/orm
• opulence/pipelines
• opulence/querybuilders
• opulence/redis
• opulence/routing
• opulence/sessions
• opulence/validation
• opulence/views

Server Config

• Opulence's tmp directory needs to be writable from PHP
• The document root needs to be set to Opulence's public directory (usually /var/www/html/public or /var/www/html/YOUR_SITE_NAME/public)

Note: You must set YOUR_SITE_DOMAIN and YOUR_SITE_DIRECTORY with the appropriate values in the configs below.

PHP Built-in Web Server Config

To run Opulence locally, use the following command:

php apex app:runlocally

This will run PHP's built-in web server. The site will be accessible at http://localhost.

Apache Config

Create a virtual host in your Apache config with the following settings:

<VirtualHost *:80>
    ServerName YOUR_SITE_DOMAIN
    DocumentRoot YOUR_SITE_DIRECTORY/public

    <Directory YOUR_DOCUMENT_ROOT/public>
        <IfModule mod_rewrite.c>
            RewriteEngine On

            # Handle trailing slashes
            RewriteRule ^(.*)/$ /$1 [L,R=301]

            # Create pretty URLs
            RewriteCond %{REQUEST_FILENAME} !-f
            RewriteRule ^ index.php [L]
        </IfModule>
    </Directory>
</VirtualHost>

Nginx Config

Add the following to your Nginx config:

server {
    listen 80;
    server_name YOUR_SITE_DOMAIN;
    root YOUR_SITE_DIRECTORY/public;
    index index.php;

    # Handle trailing slashes
    rewrite ^/(.*)/$ /$1 permanent;

    # Create pretty URLs
    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }

    location ~ \.php$ {
        include                 /etc/nginx/fastcgi_params;
        fastcgi_index           index.php;
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_param           SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass            unix:/run/php/php7.0-fpm.sock;
    }
}

Caddy Config

Add the following to your Caddyfile config:

YOUR_SITE_DOMAIN:80 {
    rewrite {
        r .*
        ext /
        to /index.php?{query}
    }
    fastcgi / 127.0.0.1:9000 php {
        ext .php
        index index.php
    }
}

Routes

Create new routes in config/http/routes.php. To handle each route, add methods to src/Application/Http/Controllers/Tutorial.php.

Views

To change the contents of each page, change the views in the resources/views directory. To change the CSS, edit public/assets/css/style.css.

If you want to create view builders, add them to src/Application/Http/Views/Builders. Then, register each view builder to the appropriate template in src/Application/Bootstrappers/Http/Views/BuildersBootstrapper.php.

Console Commands

You can run console commands running php apex from your project's root directory. To create a custom command, create a class that extends Opulence\Console\Commands\Command, and put it in the src/Application/Console/Commands directory. Then, add the fully-qualified name of your command class to config/console/commands.php.

Environment Variables

Your application is currently in the development environment. To change the environment to production, update config/environment/.env.app.php and change the ENV_NAME value to Environment::PRODUCTION.

Renaming Project

By default, an Opulence project is named "Project". To change it to something more fitting for your application, open up a console on your server, navigate to the directory Opulence was installed to, and run:

php apex app:rename Project NEW_NAME

This will automatically update all the folders, namespaces, and Composer config to use the new name.

Versioning

Opulence follows semantic versioning 2.0.0. For more information on semantic versioning, check out its documentation.