README

Introduction

StackSync is a simple, lightweight and native fullstack PHP mini-framework.

It is not a fully fledged framework and does not have all the complex features and the level of polish of other frameworks that are built by communities of professionals, therefore it is not suitable for big commercial projects or for other compagnies to use.

But it can still create powerful applications, and is more destined to be used by beginners and other developpers for personal projects.

Designed to be easy of use while having a strong foundation of the web stack of PHP, MySQL, HTML, JavaScript and CSS (or SASS/SCSS).

Requires basic knowledge of APIs, JSON, Object Oriented Programming.

The code is heavily commented and provides some examples and explanations, for a more detailed rundown, make sure to read through the documentation that covers every aspect of the mini-framework and get started.

Setup
- Installation
- Configuration
Directory Structure
Advanced
Commands
Contributions

Setup

Installation

Composer is required.

StackSync is available as a composer package, you can create a new StackSync project by running the command below in your terminal while defining the targeted folder:

composer create-project khomsiadam/stacksync project-name

Alternatively, you can download or clone the repository, then open the project and run the following command in your terminal:

composer install

This installs the dependencies for php-jwt and phpdotenv which are the only required packages.

Configuration

After creating your database, in your root directory, you will find a .env.example file. Copy and rename to .env and start filling in your database informations:

# Database Credentials: *fill with your proper database information
DB_HOST=
DB_NAME=
DB_USER=
DB_PASS=

# Data Source Name: *do not modify! $_ENV['DSN'] is used as first argument for your PDO connection
DSN=mysql:host=${DB_HOST};dbname=${DB_NAME}

# Errors and responses status for error handling for the API:
ERRORS=ON
RESPONSES=ON

# Database User Table:
USER_TABLE=user

# Database User Columns (add any needed variable for every column added in user table):
USER_ID=user_id
USER_EMAIL=email
USER_PASSWORD=password

# Database Audience Table: *The recipient table for account for 'aud' in JWT token payload
AUDIENCE_TABLE=
# Database Other Tables: *Other tables you may need, as argument for your CRUD operations in controller methods
EXAMPLE_TABLE=

# API Token Authentication Secret Keys: *fill with your own key or add new keys as needed
SECRET_KEY=

Opening your terminal, navigating to your project folder:

cd project-name

Then running this command:

composer serve:local

Will run PHP's built in development server on your local machine and browsing to http://localhost:8080 will show a welcome homepage.

Directory Structure

app/                            # The app folder is your backend folder with the main structure
|
|– config/                      # Folder containing your database, constants configuration along with the Middleware
|
|– controllers/                 # Folder containing all your controllers
|
|– core/                        # Contains the core of the mini-framework: Router, Component View system, File generation
|   |
|   |– templates/               # Folder that contains templates for file creation
|
|– migrations/                  # Any generated migration file will be here
|
|– models/                      # Folder containing all your models
|
|– seeders/                     # Any generated seeder file will be here
|
|– views/                       # Contains all files that forms a view. The content files are in the root of this folder
|   |
|   |– components/              # For view components (dynamic/static)
|   |   |
|   |   |- dynamic              # Dynamic components: part of the content
|   |   |
|   |   |- static               # Static components: part of the layout
|   |
|   |– layouts/                 # Layouts for views containing static components and the content
|
|– Application.php              # The main file that runs the application 
|
public/                         # The public folder is your frontend folder where all your assets are with the index.php file
|
|– css/                         # Folder to contain stylesheets
|
|– fonts/                       # Folder for hosting your fonts to be used with @font-face rule
|
|– icons/                       # Contains your icons
|
|– images/                      # Contains your images
|
|– js/                          # Folder for all your javascript files, libraries, modules
|
|– scss/                        # Folder to contain your SASS/SCSS files or the architecture included if used
|
|– index.php                    # Where the requests are redirected to. Routes are defined here.
|
vendor/                         # Packages folder
|
.env                            # Environement variables
|
composer.json                   # Project properties, meta data and dependencies

For a more detailed view on the directory structure be sure to check it's section in the documentation as it also provides some basic insights.

Advanced

This section dives deepers and covers all the important aspects and features.

API: The mini-framework's custom API system and the Middleware.

Controllers & Models: How controllers and models are setup.

Routing: Routing configuration for both Web routes and API endpoints.

Views: Views are managed with a Components Views System.

Migrations: A simple migrations system.

Seeding: Seed pre-defined data to your tables.

Commands

With the help of composer, there are a multiple of useful custom commands to execute in your terminal.

Run PHP's own development server on your local machine (localhost:8080):

composer serve:local

Run PHP's own development server on your local network. The address is your local IP address in your network and it can accessed by any device in the same network (ex: 192.168.1.2:8080):

composer serve:remote

*The :8080 is the default port but it can be modified in composer.json.

Apply the current migrations in app/migrations folder in the defined sequencing order:

composer migrate:apply

Drop the current applied migrations in your database. Only tables applied through the migrations system will be dropped. Any table created normally won't be affected:

composer migrate:drop

Run all seeders defined in app/seeders/DatabaseSeeder.php:

composer seed:all

Run the app/seeders/UserSeeder.php for seeding the user table:

composer seed:user

*Any created seeder can be added in app/seeders/DatabaseSeeder.php and/or have a custom script added for it under the scripts section in composer.json to be run individually.

Alternatively, you can apply current migrations then run all seeders defined:

composer migrate:apply:seed

Create a migration file while asking for it's order (that defines it's prefix and id), type (create or update), table name, auto-incremented or generated id, foreign key references and constraints:

composer make:migration

Create a seeder file while asking for the targeted table name, is the id auto-incremented or generated, import of column names as keys with empty values to be filled:

composer make:seeder

Creates both a controller and a model since they rely on each other while asking for the targeted table name, is the id auto-incremented or generated. Everything is setup automatically based on the tables columns and basic CRUD methods are defined by default for a quick start and as a base for custom methods:

composer make:controller

Enables / disables error handling:

composer errors:on

composer errors:off

Enables / disables responses from the API:

composer responses:on

composer responses:off

Contributions

Contributions are welcome. To discuss any bugs, problems, fixes or improvements please refer to the discussions section.

Before creating a pull request, make sure to open an issue first.

Committing your changes, fixes or improvements in a new branch with documentation will be appreciated.

khomsiadam / stacksync

Maintainers

Details