guzaba-platform/guzaba-platform-docs

GuzabaPlatform documentation

Maintainers

Details

github.com/AzonMedia/guzaba-platform-docs

Homepage

Source

Issues

Installs: 4

Dependents: 0

Suggesters: 0

Security: 0

Stars: 1

Watchers: 2

Forks: 0

Open Issues: 0

dev-master 2020-08-15 21:24 UTC

BSD-3-Clause 896e3440e7a2a3798a2df4d40146c2aaf67f31b9

documentationGuzabaPlatform documentation

This package is auto-updated.

Last update: 2024-11-16 06:08:20 UTC

README

Introduction

GuzabaPlatform is a plugin based system for building web applications ranging from presentational websites to corporate applications. It is based on the Guzaba 2 Framework, runs in Swoole and uses Vue for the frontend.

Swoole allows for substantial improvement in speed and concurrency compared to the traditional PHP setups and Vue gives an application like user experience.

GuzabaPlatform is in very early stages of development. There are many unfinished parts, the APIs may change, there is no test coverage yet! The documentation is scarce.

Please should you have any questions, found bugs, have feature requests or you cant get the current dev version to work please raise an issue!

Goals

GuzabaPlatform aims to provide everything needed for building an application based on Swoole, be it a simple website, microservice or large scale application. It will also include multiple commonly used components so that one can start working on your application without writing commonly found functionality.

As being based on Swoole and Guzaba 2 framework it provides for:

  • in-memory caching - the persistent nature of Swoole allows for in-memory caching! No more shared memory, APCU, Redis... no more serialization and unserialization!
  • DB connections pool - Swoole executes in code in coroutines and by having persistent memory model there is no need of connection initialization on every request
  • simultaneous tasks execution - DB queries, API requests (again with coroutines)
  • SBRM (Scope Based Resource Management) - provides for automatic transaction rollback thus avoiding the need to manually catch all cases where an exception can be thrown and manually invoke rollback(). The same is applied for the Connections management - these are freed automatically (taking into account the parent scopes!)
  • nested transactions (emulated with savepoints) - this allows for automatic partial (nested) rollback of the transaction
  • transaction events - callbacks can be added on SAVE, COMMIT, ROLLBACK.
  • ActiveRecord objects rollback on transaction rollback
  • ACL (Access Control List)
  • RBAC (Role-Based Access Control - this is in progress currently)
  • MVC (Model-View-Controller)
  • facilitate IPC (Inter Process Communication) - Swoole has multiple workers and certain actions need to be executed on all of them

GuzabaPlatform also provides (as installable packages via composer) the fundamental components for an enterprise application like:

  • permissions management on objects & classes (static methods can have permissions too!)
  • roles hierarchy model
  • Users & Roles management
  • Application server monitoring and management
  • CMS
  • CRUD
  • Assets

It will also provide some basic/common modules like:

  • catalog/shop
  • tags
  • integration with various payment providers
  • sign-in integrations with various providers

For a complete list of the available modules please go to the Packages section.

Deployment in containers

There is a docker-compose file with preset environment variables available at ./app/dockerfiles/GuzabaPlatformDev/.

Before the application is started it needs to be deployed on the host system in an empty directory with:

$ echo "{}">composer.json
$ composer config minimum-stability dev
$ composer require guzaba-platform/guzaba-platform

This will install GuzabaPlatform and run the GuzabaPlatformInstaller package that will create the needed directories & files in the root of the project. While the GuzabaPlatform depends on PHP 7.4 and Swoole these requirements are not enforced in the composer.json file as it needs to be possible to bootstrap the application from any environment and the applicattion will be always started in a container which already contains everything needed.

To deploy the application in containers execute:

$ ./app/bin/start_containers

This will start the following containers:

  • swoole (in interactive mode) on port 8081
  • redis on port 6379 (exported for debug purpose)
  • mysql on port 3306 (exported for debug purpose)
  • phpmyadmin on port 8085
  • phpredisadmin on port 8086

The login for phpmyadmin is "root" : "somerootpass".

The login for phpredisadmin is "admin" : "admin".

NOTE - on first run: On the first start of the application the database needs to be imported in MySQL. This can be done through phpmyadmin or directly over the exposed port 3306. The database dump is available at ./app/database/guzaba2.sql.

After the containers are started there will be no application running yet on port 8081. This needs to be started manually. To get into the container:

$ docker exec -it guzabaplatformdev_swoole_1 /bin/bash

If the above command produces an error this is most probably related to the container name. It may differ. To find the correct name list all the running containers with:

$ docker ps

Running in production

NOTE - on first run in production: The front end needs to be compiled - inside the container execute:

$ cd /home/local/app/public_src
$ ./build_prod

There is no need to set up local configuration in the ./app/registry because the environment file contains all the needed variables.

To start the application inside the container do:

$ /home/local/app/bin/start_server

There is also support for H2O proxy. This can be used to offload the handling of the static files to H2O and also to improve the SSL performance. Swoole is slower than H2O when running with SSL. With having H2O running as proxy it handles the SSL requests and forwards plain requests to Swoole. To start the H2O proxy execute:

$ ./app/dockerfiles/h2o_proxy/start_h2o_proxy

It starts serving HTTPS requests on port 8082.

In this setup all requests are served by H2O and only the /api/ requests are forwarded to Swoole.

Running in development mode

To start the hot reload nodejs server:

$ cd ./app/public_src
$ npm run start

Direct application startup

There is also a docker-compose file allowing the application to be started along with the other containers (instead of starting the swoole container in interactive mode):

$ /home/local/app/bin/start_server_in_container

Manual install

# require GuzabaPlatform
$ composer require guzaba-platform/guzaba-platform

# Create local configuration
$ cp app/registry/local.php.dist app/registry/local.php

# Build the front end
$ app/public_src/build_prod

Change the settings in your app/registry/local.php so you can connect to the MySQL and to the Redis server.

Running tests

To run all tests from all GuzabaPlatform packages run:

$ app/bin/run_all_tests

Current development status

  • the permissions are working but currently not configured or enforced
  • login needs improvements & additional security
  • registration needs improvements
  • the Components interface in the admin is not completed

Packages

The GuzabaPlatform is comprised of multiple Composer packages. Some of these packages are components for GuzabaPlatform and others are just dependencies and there are few main/special packages all of which you can find below.

The packages that have frontend (Vue) have their frontend automatically installed and integrated with the composer command (no need of any additional actions).

Main packages

The following packages are neither GuzabaPlatform components, neither base modules used by these. These can be installed with composer require. Usually the only one needed to be installed is GuzabaPlatform with composer require guzaba-platform/guzaba-platform. This will install all of these.

List of available components

The following GuzabaPlatform components are available as packages through Packagist and can be installed with composer require {module_name}. Currently these modules are functional but are lacking design. The GuzabaPlatform components have their package type set to "guzaba-platform-component" in composer.json and have their GitHub repository name starting with "component".

List of the components in development

The following modules can be installed with composer require {module_name}.

List of testing components

The tests are put in separate components by following the pattern VENDOR/COMPONENT-tests. By default every component installs its testing component (if there is such).

  • [guzaba-platform/guzaba-platform-tests]
  • [guzaba-platform/cms-tests]

List of modules

Additional packages that are used by GuzabaPlatform but are not GuzabaPlatform components. These packages have their package type set to "library" repository name starting with "module". These still can be installed individually with composer require but usually these will be installed as part of the components listed above.

Basic Topics

Component Development Topics

  • [New Component]
  • [New testing component]