Download the PHP package dariushha/zinux without Composer

zinux

A simple and lightweight but powerful framework supporting MVC design pattern

In this project i have tried to make its uses so simple. The zinux's policy is Convention Over Configuration which leads it to run with minimal configuration and much more flexibility, you will find it very convenient to use and develop.

There are also a zinux generator tool available.

Topics

• Requirements
• Installation
  • Windows Users
• Directory Structure
• Quick Setup
• MVC Entities
• Autoloading Classes and Files
• Naming Conventsion
• Path Resolver
• Bootstraping
  • General Definition of How To Boostrap
  • Application Bootstraps
    • Registering Application Bootstrap
  • Modules Bootstrap
    • Module Bootstrap Example
• Working With MVC Entities (Basics)
  • Passing Variables To View
  • Passing Variables To Layout
  • Changing View
  • Changing Layout
  • Loading Models
  • Loading Helpers
  • A Controller Example
• Adavnced
  • Custom Routing
  • How To Register Routers
  • Binding Custom Configuration File to Application
  • Binding Database Handler To Application
  • Adding Plugins
• Tips
• Demo Project
• Zinux Generator Tool

Requirements

• PHP version 5.5.8 or greater

If your PHP version is less than v5.5.8 but greater or equal then v5.3.10 you can use the latest version of [email protected] which is compatible with PHP v5.3.10. but consider that this version won't be updated with any changes may be made in zinux v4.0.0 or greater. But we strongly suggest that you upgrade your PHP version, because there are lots of new feature and some bug fixes in zinux v4.0.0 or greater.

---

Note: The original zinux was written and tested in PHP v5.3.10, there is no WARRANTY for PHP's other versions syntax/work-arounds compatibilities for this product.

Installation

There is a zinux installer shell script, it will automatically download and configure your system to use zinux project freely in your system.
It also installs zinux generator tool which is an handy tool to create, manipulate and provides solid security for your zinux project, for more information see Zinux Generator Tool.

You will need to have Git installed before using zinux installer.

For installation just download the zinux installer and save it at anywhere, and run the following command bash /path/to/your/zinux/installer it will do the reset.

Windows Users

For technical reasons zinux generator does not support Windows!! You just have to clone and use the framework manually.
We are sorry about this....

Some advise for PHP developers, you cannot become a professional PHP developer and develop a full scale PHP application within windows, you just cannot!! so maybe it is time to move your PHP developments on linux.

Directory Structure

Create project directory structure as follow.( or zg new PROJECT_NAME command in zinux generator tool)

  PROJECT-ROOT
    |_ Modules
        |_ SomeModule
            |_ Controllers
            |_ Models
            |_ Views
                |_ Layout
                |_ Helper
                |_ View

    |_ zinux (the library)
    |_ public_html
    |_ *
    .
    .
    .

Quick Setup

Considering above directory structure; in your PROJECT-ROOT/public_html/index.php file add following codes

and also create a .htaccess in the same directory as your index.php is and add following code route requestes to index.php.

Congratulations! you now have fully MVC magic under PROJECT-ROOT/Modules!!

You may wondering why the folder's name passed to \zinux\kernel\application\application
by considering case sensitivity, does not match with PROJECT-ROOT/Modules!?
See Path Resolver.

Simple, isn't it!?

MVC Entities

There are several entities defined in zenux framework:

• Modules
• Controllers
• Actions
• Models
• Layout
• Views
• Helpers

See naming convention for MVC Entities

Autoloading Classes and Files

zinux uses PSR-0 Standard namespace conventions to load MVC Entities follow PSR-0 Standard the zinux's autoloader may be able to load those classes and beside require_once '../zinux/zinux.php' no require needed for loading classes!

Note: classes and relative files should have same name. [not necessarily case-sensitive]

Naming Conventsion

MVC entities naming convension is as following table:

* Note: Helpers can either be class files or function files, see Loading Helpers

Path Resolver

In UNIX style OS(e.g Linux) which the directory mapping is case-sensitive so sometimes it gets hard when we developing large scale projects and keeping in mind that every file and folder should named as library's defined standard naming (i.e you cannot miss-case a letter in your namings) it sucks!!
So i have developed a very fast and effective path solver which empower the library with non-case sensitive files and folders naming style!

Note: The path solver class is as fast as file_exist() operation which is inevitable when loading items! it uses custom made cache system which is very very fast and effective and makes path solver very smooth! so you don't need to worry about runtime factors, when it comes to path resolver!

Bootstraping

General Definition of How To Boostrap

Pre-strap

Every public method in bootstrap file which has a prefix 'pre_' gets called in pre-strap phase.

Post-strap

Every public method in bootstrap file which has a prefix 'post_' gets called in post-strap phase.

Application Bootstraps

zinux uses bootstrap files(if any defined) to bootstrap the project, project boostraping has 2 stages:

pre-straps

Before executing any operation regaurding to application, zinux launches pre-straps methods, of course if any defined.(See [bellow](#registering-application-bootstrap) for how to definition pre-straps.)

post-straps

After executing the application, zinux launches post-straps methods, of course if any defined.(See bellow for how to definition post-straps.)

Application's bootstrap files can be located and addressed to anywhere under PROJECT-ROOT, I suggest put your application's boostrap files in following directory path

  PROJECT-ROOT
    |_ application
       |_ SomeAppBootstrap.php
       |_ AnotherAppBoostrap.php

    |_ Modules
    |_ zinux (the library)
    |_ public_html
    |_ *
    .
    .
    .

Note: zinux supports multiple application boostrap files.

Registering Application Bootstrap

Assume we have boostrap class called appBoostrap under PROJECT-ROOT/application directory as follow:

Note: Application bootsrap classes should inherit from \zinux\kernel\application\applicationBootstrap.

By overwriting the index file introduced in How To Use as follow:

Now your appBootstrap is registered in zinux and will get called automatically, through booting project.

Note: In zinux you are not limited to have only one project bootstrap file, you can always have multiple project bootstrap file: (But of course i discourage to have multiple project boostrap file, it may cause confusion at application level.)

Modules Bootstrap

zinux uses bootstrap file(if any exists when loading modules) to bootstrap the modules, bootstrap files are at following map:

  PROJECT-ROOT
    |_ Modules
        |_ SomeModule
            |_ Controllers
            |_ Models
            |_ Views
            |_ SomeBootstrap.php *(your module bootstrap)

        |_ DefaultModule
            |_ Controllers
            |_ Models
            |_ Views
            |_ DefaultBootstrap.php *(your module bootstrap)

    |_ zinux (the library)
    |_ public_html
    |_ *
    .
    .
    .

In bootstrap file which is a class file there are 2 kind of methods Predispatch and Postdispatch:

Predispatch

Runs before dispatching to action method! good for operations like detecting language or checking if user is logged in or not

Postdispatch

Runs after dispatching to action method! good do some data clean up or some other things

Note: zinux does not allow multiple boostrap file for boostraping modules.

Module Bootstrap Example

Working With MVC Entities (Basics)

Passing Variables To View

Varibales can passed to view in Controllers via following codes

Passing Variables To Layout

Varibales can passed to view in Controllers and Views via following codes

Changing View

View can change in Controllers via following codes

Changing Layout

Layout can change in Controllers and Views via following codes

Loading Models

When creating models' instances the zinux's autoloader will load models.
No need for require for models!

Loading Helpers

Helper can load at Anywhere if demanded helper is a class file just create object of that class the zinux's autoloader do the rest! but if they are function files they should load via following code

A Controller Example

In this example we will have a demonstration of what we talked about above

Lets assume that we have a hypothetical controller under SomeModule define in directory structure Here is a controller example (pay attention to namespace and relative controller path).

At above demo all basic operations are demonstrated. so if you catchup with the above codes you are 100% ready to use zinux library.
Cheers!

Adavnced

As i mentioned before, the porpuse of zinux is convention over configuration, and the most challenging topics in developing any applications are Project Configuration and Databse Integration.
zinux provides a very simple and flexible manner in other to bind a configuration file and database initializer.
These are optional.

Custom Routing

Some times in developing its good to have URL name convention, i.e for editing notes instead of linking /note/edit/123 you can link /note/123/edit this cause a naming unifying at URI level, i.e cou can also have /note/123/delete and ... which is much pretty and user-friendly than /note/edit/123 and also /note/delete/123.
Zinux made it very simple to have such custom routing maps, to doing so you have to have some classes (zinux supports multiple routing class, but having multiple routing classes are discouraged for sake of clean project.) which inherit from \zinux\kernel\routing\routerBootstrap, you can put your routers any where under PROJECT-ROOT directory, i suggest put it under PROJECT-ROOT/application nearby your application boostrap files, there is an example:

How does it works?
In someRoutes class in any function called from someRoutes::Fetch() by adding a route $this->addRoute() you can define custom made routes.

Note: The $1,$2 markers provide order in uri parts.

How To Register Routers

It is simple! By overwriting the index file introduced in How To Use as follow:

Binding Custom Configuration File to Application

When creating \zinux\kernel\application\application instance in PROJECT-ROOT/public_html/index.php file you can pass a instance of \zinux\kernel\application\baseConfigLoader to Startup().
and somewhere in your module you define a class which extents the abstract class \zinux\kernel\application\baseConfigLoader which would be resposible for to load configurations for your application. It can be a ini loader or XML loader, etc.

Usage example:

Lets suppose that we have a class named \vendor\tools\iniParser which is responsible for loading configurations from an ini file for your project.

Note: The zinux has its own ini parser you can use it, or define your config handler, your call.

By overwriting the index file introduced in How To Use as follow:

Accessing fetched configs

Now that we have loaded our configurations we can now get access to all loaded configurations from any we in your project via \zinux\kernel\config\config class! Example:

Easy enough, Na!?

Binding Database Handler To Application

When creating \zinux\kernel\application\application instance in PROJECT-ROOT/public_html/index.php file you can pass a instance of \zinux\kernel\application\baseInitializer as a secondary argument to constructor.
and somewhere in your module you define a class which extents the abstract class \zinux\kernel\application\baseInitializer which would be resposible for configuring database for your application

Usage example:

Lets suppose that we have a class named \vendor\db\ActiveRecord\initializer which is responsible for initializing PHP ActiveRecord for your project.

By overwriting the index file introduced in How To Use as follow:

Your application is configured to use PHP ActiveRecord as database handler and you can use PHP ActiveRecord framework freely through your project.

Still Easy, mate!?

Adding Plugins

Add plugins is so simple in zinux you just add the plugin in where ever you want under PROJECT-ROOT and start using it with out any registration or configuration!!!
What!?!?! Yup, you got it right! but make sure your have followed PSR-0 Standard discussed in Autoloading Classes And Files in your plugins.

Actually the zinux looks the entire project as pluging by itself!!

Simple, Ha!?

Note: In case of using third-party libraries you may encounter with one of two situations bellow :

Situation #1

In case of using third-party libraries which has applied its own PSR-0 Standard you can introduce its root directory to zinux like bellow.

By overwriting the index file introduced in How To Use as follow:

Note: If the third-party does not follow PSR-0 Standard you have to apply the Situation #2 bellow. actually both are the same, but in Situation #1 the zinux does the autoloading for you, in Situation #2 you have to define your own autoloader which most third-party libraries do it, you just have to call it. see bellow.

Situation #2

In case of using third-party libraries has not applied PSR-0 Standard and also which is hard to apply PSR-0 Standard to it, following Tip may become usefull!

Tip: If you are using and third-party plugin, you don't need to standardize entire plugin with PSR-0 Standard (notice that we didn't change any PHP-ActiveRecord namespaces in Binding Database Handler To Application!!)
You just create a initializer class in that plugin which define a autoloader for that pluging! In Binding Database Handler To Application example the autoloader is defined in :

Then you call the plugin autoloader just before making application run! i.e by overwriting the index file introduced in How To Use as follow:

Tips

Request Types

The zinux supports request types i.e you can have a URI like /news/feed.json which points to NewsController and FeedAction you can ouput feeds according to request type (in here json) in NewsController::FeedAction()! default is html.

Demo Project

You can download a demo project from zinux-demo.

Zinux Generator Tool

Zinux generator tool is an efficient appliction designed to make use of zinux project even easier than it is, and also makes you develop more, in a short time.
For an example, just by typing following command you will have your preoject ready:

The above command will creates a whole new project containing defaultModule, appBootstrap, appRoutes, indexConroller, etc.

Or for an other example the following command will creates a new action and its related view in any controller and in any desired module:

For more information see Zinux Generator Project's official page.

It also provides solid code-level security for your project, by solid encryption/decryption algorithms designed to encrypt or decrypt your project's code files.