Setup

To install the olodoc app, the Php and composer package must be installed on your computer.

Requirements

Only Php 7.4 and above versions are supported.

Follow the steps below to create an Olodoc project.

git clone [email protected]:olomadev/olodoc-skeleton.git myproject

Go to your project root

cd /var/www/myproject

Install composer packages

/var/www/myproject$ composer install

Give 777 permision for /data/tmp, /data/docs folders and sitemap.xml file.

chmod 777 -R /var/www/myproject/data/tmp
chmod 777 -R /var/www/myproject/data/docs
chmod 777 /var/www/myproject/public/sitemap.xml

CLI Php.ini

You have to set pcre.jit=0 in your CLI php.ini file, otherwise you will get PREG_JIT_STACKLIMIT_ERROR error for long replace operations.

Open your cli php.ini file:

vim /etc/php/8.3/cli/php.ini

Set pcre.jit to "0".

[Pcre]
; Enables or disables JIT compilation of patterns. This requires the PCRE
; library to be compiled with JIT support.
pcre.jit=0

Restart your server.

sudo service apache2 restart

Apache2

Enable Apache mod_rewrite plugin.

sudo a2enmod rewrite

The AllowOverride option for directories in the apache2.conf file must be All.

vim /etc/apache2/apache2.conf

Change this option from the default None to All.

<Directory /var/www/>
    Options Indexes FollowSymLinks
    AllowOverride All
    Require all granted
</Directory>

Create a hosts file.

cd /etc/apache2/sites-available
cp 00-default.conf example.local.conf
vim example.local.conf

In your Apache host file, the DocumentRoot configuration must be set to the yourproject/public/ folder. It is recommended to set DirectoryIndex to index.php. ServerName is set to example.local in this example.

<VirtualHost *:80>

    SetEnv "APP_ENV" "local"
    ServerName example.local
    ServerAlias *.example.local   # subdomain support
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/myproject/public/
    DirectoryIndex index.php

    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined

</VirtualHost>

Save your vhost file and restart the apache server.

a2ensite example.local.conf
sudo service apache2 restart

.htaccess

Configuration requires the .htaccess file as follows. This file is located in the /public folder.

Linux Host File

In this example, the project is defined as example.local in the /etc/hosts file.

127.0.1.1       example.local

If you are setting up a multilingual project via a subdomain, add the languages you plan to support as follows.

127.0.1.1       example.local
127.0.1.1       en.example.local
127.0.1.1       tr.example.local

Local Environment

To work in a local environment,

1. Copy your local.php.dist file in your project root directory and save it as local.php into your /config/autoload/ folder.
2. Update your base_url which shown below at line number 32.
3. Update your root_path which shown below at line number 35.

<?php
/**
 * Development-only configuration.
 *
 * Put settings you want enabled when under development mode in this file, and
 * check it into your repository.
 *
 * Developers on your team will then automatically enable them by calling on
 * `composer development-enable`.
 */

declare(strict_types=1);

use Laminas\ConfigAggregator\ConfigAggregator;

return [
    //
    // olodoc
    // 
    'olodoc' => [
        'default_version' => '1.0',
        'available_versions' => [
            '1.0',
            '2.0'
        ],
        'default_locale' => 'en',
        'available_locales' => [
            'en',
            'tr'
        ],
        'http_prefix' => 'http://', // http(s) prefix
        'base_url' => '{locale}.example.local/', // or "example.local/{locale}"
        'images_folder' => '/public/', // location of your "/images" folder
        'remove_default_locale' => true, // removes default locale from base url: "en.example.local" => "example.local"
        'config_path' => '/config/olodoc/', // your config file path 
        'root_path' => '/var/www/myproject', // your project root 
        'html_path' => '/data/docs/', // save location for your ".html" document files
        'xml_path' => '/public/sitemap.xml',
        'sitemap_base_url' => 'https://example.com', // sitemap.xml base url
        'build_sitemapxml' => true,
        'base64_convert' => false, // if true all images are converted to base64 encoded strings
        'anchor_generations' => true, // it will enable anchor generations for all routes
        'anchor_parse_query' => '//h2|//h3|//h4|//h5|//h6',
        'anchors_for_index_pages' => true, // if false anchors will not be created in index.html routes
    ],

    // Toggle the configuration cache. Set this to boolean false, or remove the
    // directive, to disable configuration caching. Toggling development mode
    // will also disable it by default; clear the configuration cache using
    // `composer clear-config-cache`.
    ConfigAggregator::ENABLE_CACHE => false,

    // Enable debugging; typically used to provide debugging information within templates.
    'debug' => true,
];

Run Your Application

If everything went well, you can run your first application by typing your project address into your browser as follows:

About Php Mezzio Framework

Olodoc uses the super fast micro framework called Mezzio. If you would like to get more detailed information about the Mezzio framework, you can take a look at the resources below.