add container helpers; constuct public directory-tree

1 files changed, 96 insertions, 171 deletions

diff --git a/README.md b/README.md
index fb92086..e463f3b 100644
--- a/README.md
+++ b/README.md
@@ -1,266 +1,191 @@
-## x-anom
-### X is ANOther Mvc
+# x-anom 
+(another MVC framework)
 
-x-anom is an Object-Oriented MVC php-framework.
 
-Main advantages of the framework:
 
-* It is super-light and fast;
-* Core has almost zero dependences and contains almost anything you need to start and optimize a server-based web-application.
-* It is extensible especialy if you use Composer (which is recommended, though not required)
-* Handles security; and as long as you write code using secure practices, it will be secure
-* It's easy to configure, easy to code, easy to use
+## pre-Check
 
+Update ```~./container/config/composer-copy.json``` according to
+```~./composer.json``` or vice-versa. You actualy need just one of them;
+if pulling the project into a server (bare-metar/vps/shared etc) you only
+need the first; if pulling into container you need the second/
 
 
-### Requirements
+On a Linux system you can also create a link from the one file to the other
+(then you need to use ralative paths on autoload.classmap section).
 
-* PHP 8+
-* Some webserver (Apache/Nginx)
-* Some SQL server (MySQL/MariaDB/Postgress)
-* Basic knowledge of php and SQL
+When deploying on PRODUCTION make sure that all development routes are deleted
+and debuging messages are disabled.
 
 
 
 
-### What is included
+## Build
 
-Core components:
+    docker build -t x-anom .
 
+Force build without using cache:
 
-#### Router
+    docker build --no-cache -t x-anom .
 
-Routes request to the appropriate Controller
-- matches static paths
-- matches dynamic paths through regex expressions
-- takes care of request-method
 
 
-#### Controller and Model
 
-(just write your Controller and Model classes)
+## Run
 
+    docker-compose up
 
-#### View (rendering engine)
+Force rebuild; then run:
 
-Usually you just need to call the render_view(template, data) function.
-For templating we use the php short-tag syntax.
+    docker-compose up --build
 
-main functions:
 
-* load_template( template, data)
 
-* render_view( view_file , data )
 
-* load_asset( type, assets_array )
+## Remove builded containers
 
-* set_headers( content_type, ttl, more_array )
+    docker-compose down
 
-* render_text( data, content_type, ttl )
 
-* reply_json( data, ttl )
 
 
-#### Class autoloader
+## While developing...
 
-Composer is recomende; 
-but if is not available this one will do the job
+By default autoloading is handled by Composer (this is highly recommended).
+While developing your application (or the framework itself) you will need to
+update the autoloading of your new classes. To do so, attach a shell, change
+to ```/var/www``` directory and run ```composer dump-autoload```
 
+    cd /var/www
 
-#### Caching
+    composer dump-autoload
 
-* File Caching mechanism
+If Composer is not an option and you use the framework's autoload implementation
+(enabling ```define('AUTOLOADER' , '../core/helpers/autoload.php');```),
+do not forger to update the (new) paths to your new classes in the ```CLASSPATHS```
+array . Both ```AUTOLOADER``` and ```CLASSPATHS``` definitions can be found
+into ```core/confing/anom_settings.php``` file.
 
-* Redis Cache
 
-* Memcached Caching
 
 
-#### Session Management
+## XDebug
 
-* DefaultSession: psevdo-handler with passthrough methods
+anom comes with most configuration of XDebug ready; all you need is
 
-* FileSession: custom file-based session handler
+1. on Doockerfile: uncoomment the commands under XDebug section
 
-* DatabaseSession: database session handler
+2. on docker-compose.yml: uncomment the services.web.extra_hosts section
 
+3. you may need configure your ide to listen onto XDebuger host port
 
+example: 
+for vscode you need to add a ~./.vscode/launch.json file like this:
 
-#### More
+    {
+        "version": "0.2.0",
+        "configurations": [
+            {
+                "name": "Listen for Xdebug",
+                "type": "php",
+                "request": "launch",
+                "port": 9003,
+                "pathMappings": {
+                    "/var/www/html": "${workspaceRoot}/html"
+                }
+            }
+        ]
+    }
 
-* Proxy design pattern
 
-* Error handling
 
-* Repository
 
-* Cli interface (*summarizes anom*)
+## Customization
 
+The project includes several almost-ready-to-use technologies;
+You can enable / customize / disable / configure all these with a few edits.
 
+Each time you change the configuration of your environment, do not forget to set the
+related parameters on the main configuration file (```/core/config/anom_settings.php)```
+and/or define environmental variables or credentials to the ```/core/auth/.env``` file.
 
+NOTE: #1
+We assume that you use composer; if not, then whatever composer does you have to
+make it manually (copy dependency files and setup the autoloader's paths).
 
+NOTE: #2
+There is no need to use both Redis and Memcached, thus I have not test if these
+two caching technologies will work together using the proposed comfiguration.
 
-### Other features
 
-* Docker ready
 
-You can run the framework as is in a Docker environment;
-Also. you can edit just a bit the configuration files to customize the project
-to support various technologies; Check the README file in the project's root
-folder to find out more.
+#### Redis
 
+To enable Redis...
 
+Onto docker-compose.yml:
 
-### What is not included
+1. Uncomment the lines of 'redis' section; Your Redis-server host name will be the one that is specified in the container_name field (default: redis)
 
-* It lacks a query builder (SQL is easy and very powerful); do not forget to use prepared statements for all your SQL queries.
+2. Uncomment the networks subsections; web-server and Redis-server will communicate through a bridge network
 
-* TODO: User-Role based administration class.
+3. With composer:
 
-* TODO: Shoping-Cart class.
+Include predis/redis into your project's requirements using ```/docker/config/composer-redis.json```
+as your composer.json file -or- install it via:
 
+    composer require predis/predis
 
 
-## Life (and death) of a Client_Request–Server_reply session
 
-1. THE REQUEST: client makes a request -> request arives to the server -> .htaccess sends the request to the index.php
+#### Memcached
 
-2. index loads Configuration (constants.php + config.php) and AUTOLOADER in order load classes easily
+To host the Memcached service:
 
-3. index loads init.php -> after initialization the APP is READY -> index loads the routes; Route::run() -> the APP is RUNNING
+1. Onto docker-compose.yml: uncomment the lines of 'memcached' section; Memcached-server host name will be the one that is specified in the container_name field (default: anomemcached)
 
-4. Router resolves the request pattern and calls a Controller
+2. Onto Dockerfile: uncomment the lines under subsection 'Install Memcached'
 
-5. (if needed) Controller asks data from the Model; then responds a reply to the client using **render** functions -> APP dies
 
 
+* TODO: Maria database
 
-## Direcrtory structure
 
-NOTE: directory structure needs updata, but the main structure ramains untouched.
+* TODO: Adminer
+(https://stackoverflow.com/questions/33631085/how-to-use-adminer-with-composer-autoload-php)
 
-    .
-    |-- container               * for docker/container configuration
-    |   |-- bin                     * scripts
-    |   `-- config                  * settings
-    |
-    |-- core                    * core code
-    |   |-- auth                    * authentication and credentials
-    |   |
-    |   |-- config                  * application parametres
-    |   |   |-- config.php
-    |   |   |-- constants.php
-    |   |   |-- credentials.php
-    |   |   `-- init.php
-    |   |
-    |   |-- classes                 * core classes
-    |   |   |-- cacher    
-    |   |   |-- Benchmark.php
-    |   |   |-- Database.php
-    |   |   |-- Route.php
-    |   |   |-- Security.php
-    |   |   `-- Session.php
-    |   |
-    |   `-- helpers                 * core helpers
-    |       |-- autoload.php            
-    |       |-- error-handling.php
-    |       `-- render.php
-    |
-    |-- data                    * folder for batch data-imports to database
-    |
-    |-- html                    ** PUBLIC directory
-    |   |-- app                     * APP
-    |   |   |-- Controllers             * Controllers
-    |   |   |   |-- Art.php
-    |   |   |   `-- ...
-    |   |   |
-    |   |   |-- Models                  * Models
-    |   |   |   |-- Art_model.php
-    |   |   |   `-- ...
-    |   |   |
-    |   |   |-- Views                   * Views
-    |   |   |   |-- group.php
-    |   |   |   `-- item.php
-    |   |   |
-    |   |   `-- routes.php              * application routes
-    |   |
-    |   `-- cache                   * Caching folder
-    |
-    `-- vendor              * Vendor classes and autoloader
-        |-- composer
-        `-- ...
 
+* TODO: phpMyAdmin
 
 
+* Apache
 
-## Naming Conventions and good practices
 
-1. Keep Controllers, Models, Views in their folders
+* Opcache and JIT
 
-2. Organize View elements in subfolders
 
-3. Controller and Model names shall be camelcased;
-   - fist letter should be Uppercase;
-   - classes shall be named exactly as their filenames
+TODO:
 
-4. Model names shall be suffixed with _model
+## Staging
 
-5. Comment every-single Controller/Model/class and comment every method
+#### Build
 
-6. On Views (php templates) use php short-tags when possible
-   - Views are about rendering data; avoid complex-logic
-   - [if/else], [foreach] and some flag/temp [variables] sould be fair enough
+#### Deploy
 
-7. All of the above rules are strongly recommended (although not obligatory);
 
+## Production
 
+### Build
 
-## Notes and brainstorming
+### Deploy
 
-### for template system check
-    https://css-tricks.com/php-is-a-ok-for-templating/
+! Run the above commands ONLY when you need to manually deploy the app to Cloud Run, otherwise everything is automated using Cloud Builds
 
-### for rendering system you may check volt too
-    https://docs.phalcon.io/4.0/en/volt
 
 
 
-## Brainstorming
+## Notes
 
-* take care of various hacks
-    chk: https://stackoverflow.com/questions/1996122/how-to-prevent-xss-with-html-php
+* '~./' refers to the root of the project
 
-* HTML to MarkDown!
-    chk: https://github.com/thephpleague/html-to-markdown
-
-
-
-
-
-VIEW data
-
--> ceo  -> title
-        -> description
-        -> keywords
-        -> ...
-
--> content  -> view : view_filename
-            -> key  : some_variable_name
-            -> data : the_data
-
-
-
-
-## Knowledge Requirements 
-
-## Tools of work
-
-None of the following tools is necessary, but they will help very very-much.
-
-- Composer
-
-- Docker
-
-- Code editor
-
-- Coffee + Nicotine
+* Furhter documentation about the framework can be found in ~./core/README.md