search

ivantcholakov / starter-public-edition-4

A PHP application starter, based on CodeIgniter 3
MIT License
164 stars 89 forks source link
codeigniter php

readme

A PHP Application Starter, Version 4, Based on CodeIgniter

Project Repository

https://github.com/ivantcholakov/starter-public-edition-4

Note

This version supports multiple applications.

PHP

If you are a beginner with little or no PHP experience, you might need to read a training tutorial like this one:

PHP Tutorial for Beginners: Learn in 7 Days, https://www.guru99.com/php-tutorials.html

CodeIgniter 3 Documentation

https://www.codeigniter.com/userguide3/

Requirements

PHP 8.0.2 or higher, Apache 2.4 (mod_rewrite should be enabled). For database support seek information within CodeIgniter 3 documentation.

For UTF-8 encoded sites it is highly recommendable the following PHP extensions to be installed:

Installation

Download source and place it on your web-server within its document root or within a sub-folder. Make the folder platform/writable to be writable. It is to contain CodeIgniter's cache, logs and other things that you might add. Open the site with a browser on an address like this: http://localhost/starter-public-edition-4/public/

On your web-server you may move one level up the content of the folder public, so the segment public from the address to disappear. Also you can move the folder platform to a folder outside the document root of the web server for increased security. After such a rearrangement open the file config.php (public/config.php before rearrangement), find the setting $PLATFORMPATH and change this path accordingly. The file public/config.php contains also the ENVIRONMENT setting that can be switched among development, testing, and production mode. By default ENVIRONMENT is set to 'production'.

The following directories (the locations are the original) must have writable access:

platform/upload/
platform/writable/
public/cache/
public/editor/
public/upload/

Have a look at the files .htaccess and robots.txt and adjust them for your site. Within the directory platform/applications you will by default two applications - "front" and "admin". Have a look at their configuration files. Also, the common PHP configuration files you may find at platform/common/config/ folder.

The platform auto-detects its base URL address nevertheless its public part is on the document root of the web-server or not. However, on production installation, site should be accessed only through trusted host/server/domain names, see platform/common/config/config.php , the configuration settings $config['restrictAccessToTrustedHostsOnly'] and $config['trustedHosts'] for more information.

Installation on a developer's machine

In addition to the section above, it is desirable on a developer's machine additional components to be installed globally, they are mostly to support compilation of web resources (for example: less -> css, ts -> js). The system accesses them using PHP command-shell functions.

When installing the additional components globally, the command-line console would require administrative privileges.

node -v
npm -v
sudo npm install -g n

Updating Node.js:

sudo n lts

Updating npm:

sudo npm i -g npm

Updating all the globally installed packages:

sudo npm update -g

Another way for global updating is using the interactive utility npm-check. Installing:

sudo npm -g i npm-check

And then using it:

sudo npm-check -u -g
sudo npm install less -g

Then the following command should work:

lessc -v
sudo npm -g install postcss-cli

And this command should work:

postcss -v
sudo npm -g install autoprefixer
sudo npm -g install cssnano
sudo npm -g install typescript-compiler

This command should work:

tsc -v

On compilation of huge web-resources Node.js might exaust its memory, in such case try (the value may vary):

export NODE_OPTIONS=--max-old-space-size=8192

Coding Rules

For originally written code a tab is turned into four spaces. This is the only strict rule. Standard PSR rules are welcome, but it is desirable code not to be 'compressed' vertically, use more meaningful empty lines that would make code more readable and comfortable.

Additional Features

Instead of:

// Filename: Welcome.php
class Welcome extends Base_Controller {
    // ...
}

you can write:

// Filename: Welcome_controller.php
class Welcome_controller extends Base_Controller {
    // ...
}

Thus the class name Welcome is available to be used as a model name instead of those ugly names Welcome_model, Welcome_m, etc. The technique of this hack is available, but it is not mandatory.

How to use this feature:

Enable the configuration option 'parse_i18n':

$config['parse_i18n'] = TRUE;

Then in your views you can use the following syntax:

<i18n>translate_this</i18n>

or with parameters

<i18n replacement="John,McClane">dear</i18n>

where $lang['dear'] = 'Dear Mr. %s %s,';

Here is a way how to translate title, alt, placeholder and value attributes:

<img src="https://github.com/ivantcholakov/starter-public-edition-4/raw/master/.." i18n:title="click_me" />

or with parameters

<img src="https://github.com/ivantcholakov/starter-public-edition-4/raw/master/.." i18n:title="dear|John,McClane" />

You can override the global setting 'parse_i18n' within the controller by inserting the line:

$this->parse_i18n = TRUE; // or FALSE

Parsing of <i18n> tags is done on the final output buffer only when the MIME-type is 'text/html'.

Note: Enabling globally the i18n parser maybe is not the best idea. If you use HMVC, maybe it would be better i18n-parsing to be done selectively for particular html-fragments. See below on how to use the Parser class for this purpose.

Instead of:

$this->load->library('parser');

write the following:

$this->load->parser();

Quick tests:

// The default parser.
$this->load->parser();
echo $this->parser->parse_string('Hello, {name}!', array('name' => 'John'), TRUE);

There are some other parser-drivers implemented. Examples:

// Mustache parser.
$this->load->parser('mustache');
echo $this->mustache->parse_string('Hello, {{name}}!', array('name' => 'John'), TRUE);
// Parsing a Mustache type of view.
$email_content = $this->mustache->parse('email.mustache', array('name' => 'John'), TRUE);
echo $email_content;
// Textile parser
$this->load->parser('textile');
echo $this->textile->parse_string('h1. Hello!', NULL, TRUE);
echo $this->textile->parse('hello.textile', NULL, TRUE);
// Markdown parser
$this->load->parser('markdown');
echo $this->markdown->parse_string('# Hello!', NULL, TRUE);
echo $this->markdown->parse('hello.markdown', NULL, TRUE);
// Markdownify parser
$this->load->parser('markdownify');
echo $this->markdownify->parse_string('<h1>Hello!</h1>', NULL, TRUE);
echo $this->markdownify->parse('hello.html', NULL, TRUE);
// LESS parser
$this->load->parser('less');
echo $this->less->parse_string('@color: #4D926F; #header { color: @color; } h2 { color: @color; }', NULL, TRUE);
echo $this->less->parse(DEFAULTFCPATH.'assets/less/lib/bootstrap-3/bootstrap.less', NULL, TRUE);

Within the folder platform/common/libraries/Parser/drivers/ you may see all the additional parser drivers implemented. Also within the folder platform/common/config/ you may find the corresponding configuration files for the drivers, name by convention parser_driver_name.php. Better don't tweak the default configuration options, you may alter them directly on parser call where it is needed.

The simple CodeIgniter's parser driver-name is 'parser', you may use it according to CodeIgniter's manual.

Enanced syntax for using parsers (which I prefer)

Using the generic parser class directly, with specifying the desired driver:

$this->load->parser();

// The fourth parameter means Mustache parser that is loaded automatically.
echo $this->parser->parse_string($mustache_template, $data, true, 'mustache');

// The fourth parameter means Markdown and auto_link parsers parser to be applied in a chain.
echo $this->parser->parse_string($content, null, true, array('markdown', 'auto_link'));

// The same chaining example, this time a configuration option of the second parser has been altered.
echo $this->parser->parse_string($content, null, true, array('markdown', 'auto_link' => array('attributes' => 'target="_blank" rel="noopener"')));

Using parsers indirectly on rendering views:

// You don't need to load explicitly the parser library here.

// The fourth parameter means that i18n parser is to be applied.
// This is a way to handle internationalization on views selectively.
$this->load->view('main_menu_widget', $data, false, 'i18n');

Using a parser indirectly with Phil Sturgeon's Template library:

// You don't need to load explicitly the parser library here.

$this->template
    ->set(compact('success', 'messages', 'subject', 'body'))
    ->enable_parser_body('i18n')  // Not elegant enough, sorry.
    ->build('email_test');

Gulp/Webpack and etc. package managers from the Javascript world might be annoying burden for a PHP-developer. In order to make this matter easier, a web-asset compilator has been implemented, it uses internally the corresponding parsers. First, the compiler's tasks must be specified by names, see the configuration file platform/common/config/assets_compile.php.

Have a look at platform/common/config/assets_compile.php file. It contains a list of files (sources, destinations) to be used for LESS to CSS compilation. You may edit this list according to your needs. Before compilation, make sure that destination files (if exist) are writable and their containing folders are writable too. A simple example:

    ...
    [
        'name' => 'my_task',
        'type' => 'less',
        'source' => DEFAULTFCPATH.'themes/front_default/src/my.less',
        'destination' => DEFAULTFCPATH.'themes/front_default/src/my.min.css',
        'less' => [],
        'autoprefixer' => ['browsers' => ['> 1%', 'last 2 versions', 'Firefox ESR', 'Safari >= 7', 'iOS >= 7', 'ie >= 10', 'Edge >= 12', 'Android >= 4']],
        'cssmin' => [],
    ],
    ...

As you can see, there are source and destinations files, and a chain of parsers with their specific options. The type of the task here is the name of the first parser to be applied. Practically, more complex tasks might be needed when CSS and Javascripts are merged into a single result file. For this purpose there are two special task-types: 'merge_css' and 'merge_js', see an example:

    [
        'name' => 'front_default_css',
        'type' => 'merge_css',
        'destination' => DEFAULTFCPATH.'themes/front_default/css/front.min.css',
        'sources' => [
            [
                'source' => DEFAULTFCPATH.'themes/front_default/src/front.less',
                'type' => 'less',
                'less' => [],
                'autoprefixer' => ['browsers' => ['> 1%', 'last 2 versions', 'Firefox ESR', 'Safari >= 7', 'iOS >= 7', 'ie >= 10', 'Edge >= 12', 'Android >= 4']],
                'cssmin' => [],
            ],
            [
                'source' => DEFAULTFCPATH.'assets/scss/lib/sweetalert/sweetalert.scss',
                'type' => 'scss',
                'autoprefixer' => ['browsers' => ['> 1%', 'last 2 versions', 'Firefox ESR', 'Safari >= 7', 'iOS >= 7', 'ie >= 10', 'Edge >= 12', 'Android >= 4']],
                'cssmin' => [],
            ],
        ],
        'before' => '_prepare_semantic_source',
        'after' => [
            '_create_sha384',
            '_create_sha384_base64',
        ],
    ],

Within the example 'before' and 'after' elements are callbacks that do additional user-defined actions before and after the correspinding task is executed.

There is a defined special task-type 'copy' that allows merging already minified CSS or JavaScript without any processing.

Compilation is to be done from command-line. Open a terminal at the folder platform/public/ and write the following command:

php cli.php assets compile

Or, you may choose which tasks to execute by pointing at their names:

php cli.php assets compile task_name_1 task_name_2 task_name_3 ...

The Playground

It is hard everything about this platform to be documented in a formal way. This is why a special site section "The Playground" has been created, aimed at demonstration of platform's features/concepts. You may look at the examples and review their code.

A contact form has been created that with minimal adaptation you may use directly in your projects.

If you have no previous experience with CodeIgniter, get familiar with its User Guide first: https://www.codeigniter.com/user_guide/

Installed Composer Packages (Not a Full List)

Package Description Usage
codeigniter/framework CodeIgniter 3 Everywhere
ivantcholakov/codeigniter-phpmailer The wrapper library for PHPMailer. Sending emails
fg/multiplayer Builds customizable video embed codes from any URL Multiplayer library
scssphp/scssphp A compiler for SCSS written in PHP Parser 'scss' driver
guzzlehttp/guzzle A HTTP client library Playground, REST service test
whichbrowser/parser Useragent sniffing library for PHP Which_browser library
erusev/parsedown Parser for Markdown Parser 'markdown' driver
erusev/parsedown-extra An extension of Parsedown that adds support for Markdown Extra Parser 'markdown' driver
pixel418/markdownify A HTML to Markdown converter Parser 'markdownify' driver
mustache/mustache A Mustache template engine implementation in PHP Parser 'mustache' driver
netcarver/textile Textile markup language parser Parser 'textile' driver
twig/twig Twig template language for PHP Parser 'twig' driver
ezyang/htmlpurifier Standards compliant HTML filter written in PHP admin and user HTML filters for the online editor
t1st3/php-json-minify A JSON minifier Parser 'jsonmin' driver
matthiasmullie/minify CSS & JS minifier Parser 'cssmin' and 'jsmin' drivers
phpmailer/phpmailer An email creation and transfer component for PHP The custom Email library
yohang88/letter-avatar Generates user avatars based on name initials userphotos application
intervention/image Image handling and manipulation library yohang88/letter-avatar
athlon1600/php-proxy A web proxy script written in PHP. Demo feature for previewing the error logs

Real Life Usage

Reported by Zashev Design - Web Design Studio

Reported by Krishna Guragai, @krishnaguragain

Credits

License Information

For original code in this project:
Copyright (c) 2012 - 2022:
Ivan Tcholakov (the initial author) ivantcholakov@gmail.com,
Gwenaël Gallon.
License: The MIT License (MIT), http://opensource.org/licenses/MIT

CodeIgniter:
Copyright (c) 2008 - 2014, EllisLab, Inc. (https://ellislab.com/)
Copyright (c) 2014 - 2019, British Columbia Institute of Technology (http://bcit.ca/)
Copyright (c) 2019 - 2022, CodeIgniter Foundation (https://codeigniter.com/)
License: The MIT License (MIT), http://opensource.org/licenses/MIT

Third parties:
License information is to be found directly within code and/or within additional files at corresponding folders.

Donations

Ivan Tcholakov, November 11-th, 2015: No donations are accepted here. If you wish to help, you need the time and the skills of being a direct contributor, by providing code/documentation and reporting issues. Period.