README

A simple & fast PHP starter kit for web app.

partez is a PHP starter kit designed to help developers quickly set up and manage a PHP web application. It includes robust backend support with streamlined front-end automation via bricolo, a JS package that compiles assets, serves your app, and provides live reloading for a smooth development workflow.

Getting Started
- Requirements
- Installation and Setup
How It Works
Bricolo JS Automation
- Configuration
- Usage
Built With
Contributing
Contact

Getting started

Requirements

Composer for backend dependency management.
Node.js (v12 or higher) and npm for bricolo to enable asset compilation and live reloading.

Installation and Setup

Project Setup: Create a new folder for your project and open a terminal in it.
Install the PHP Framework: Run this command to install partez and its dependencies:

composer create-project abollinger/partez .

Create a .env File: If not automatically created, create a .env file at the project root. You can use .env.example as a reference.
Automatic Front-End Setup with bricolo: bricolo is automatically installed via npm as part of the post-create command in composer.json. This includes asset compilation and live reloading. If you run the create-project command with --no-script options, you should run npm install to make sure that bricolo will be available.
Run the Development Server: Start the server with the command below to view the app in your browser at localhost:1234 (the port may change according to the other ports already in use on your machine. Please check the log in the console):

composer serve

How it works

Configuration

HTML Customization: Modify the HTML layout in src/views/Layout.twig to adjust the document head.
Routing: Routes are automatically derived from controllers in src/Controllers using specific annotations (see below).

The Router

Define routes in src/Controllers files using PHP annotations:

/**
 * @Route("/", name="Home", auth=false)
 */

URI ("/") is mandatory.
Name (name="Home") specifies the route's name.
Authentification (auth=false) restricts the access if set to true (default is false).

The Pages

Controllers in src/Controllers extend the main controller (Abstract/Controller.php). The init() method call renderPage("Page.twig") to render the Twig template. Each page extends the main layout in src/views/Layout.twig.

The Public Folder

The public directory houses index.php, as well as js, css and images folders, which can be customized freely.

The API

A basic API is available in api/ and runs on a MySQL database.

Bricolo JS Automation

The Partez PHP framework includes bricolo as an automation tool for front-end tasks, so you can focus on development without needing to handle asset compilation or live reloading setup yourself. bricolo is installed automatically during setup, and it's already configured with a bricoloconfig.json file that defines custom settings to integrate with this project.

You can find more information on the npm of the bricolo (js) package.

Bricolo JS Configuration

bricolo is automatically installed within the project and configured with the file bricoloconfig.json:

{
    "phpServer": {
        "port": 8080,
        "command": "composer serve p={port}"
    },
    "jsBuild": {
        "entry": "assets/js/main.ts",
        "output": "public/js/bundle.js"
    },
    "sassBuild": {
        "entry": "assets/css/main.scss",
        "output": "public/css/style.min.css"
    },
    "watch": {
        "directories": [
            "src/**/*.php",
            "src/**/*.yaml",
            "view/**/*.twig",
            "public/**/*.css",
            "public/**/*.js",
            "public/**/*.svg"
        ]
    },
    "server": {
        "port": 1234
    }
}

Configuration Overview

PHP Server: The PHP server will run on port 8080 using the command composer serve p={port}.
Asset Compilation:
- JavaScript: Compiles assets/js/main.ts into a bundle at public/js/bundle.js.
- CSS: Compiles assets/css/main.scss into a minified CSS file at public/css/style.min.css.
File Watching:
- bricolo monitors files in specified directories (src/**/*.php, view/**/*.twig, public/**/*.css, etc.) for changes, which will trigger asset compilation and live browser reload.
Live Reload Server: The development server is set to run on port 1234 for hot reloading.

Usage

After creating the project, you can simply start the bricolo automation and server:

npm run serve

Or, if you prefer, use the command directly:

npx bricolo serve

This command will:

Start the PHP server on port 8080.
Compile and watch for changes in JavaScript and Sass files.
Automatically reload the browser at localhost:1234 whenever changes are detected in watched files.

Build with

This kit is build in PHP, using as much as possible the MVC pattern. We use the Twig template engine to generate the pages.
Style is now powered by Bootstrap v5.2, using the simple CDN link.
You can add JS scripts in the public folder or wherever you want, as mentioned earlier.

The basic structure is:

.
├── api/
│   ├── Abstract/ (Basic logic of the api)
│   ├── Config/ (Configuration files)
│   ├── Controllers/
│   │   └── [Controllers, typo is <Name>Controller.php]
│   ├── Models/
│   │   └── [Models, typo is <Name>Model.php]
│   ├── Provider/ (Providers logic like Database or any other resources provider)
│   ├── Router/ (main router logic for the api)
│   ├── View/ (set up a standardized response for every API request)
│   └── Starter.php
├── assets/
│   ├── css/ (Contains scss files that will be compiled into css in the public/css folder, based on bricolo js automation)
│   └── js/ (Contains typescript scripts that will be compiled into js in the public/js folder, based on bricolo js automation)
├── public/
│   ├── css/
│   ├── images/
│   ├── js/
│   └── index.php
├── src/
│   ├── Abstract/ (Basic logic of the app)
│   ├── App/ (Starter of the app)
│   ├── Config/ (Some configuration files like Bootstrap or Session)
│   ├── Controllers/
│   │   └── [Controllers, typo is <Name>Controller.php]
│   └── Router/ (Contains main Router logic)
├── views/ (Contain Twig templates for your app)
└── .env

Contributing

We welcome contributions! Here’s how to contribute:

Fork the project.
Create your feature branch: git checkout -b features/Myfeature.
Commit your changes: git commit -m "✨ Introducing Myfeature!".
Push to Github: git push origin features/Myfeature.
Open a Pull Request.

Contact

If you have any questions, feel free to reach out:

Antoine Bollinger - LinkedIn - antoine.bollinger@gmail.com

You can talk to me in 🇫🇷, 🇧🇷 or 🇬🇧.

abollinger / partez

Maintainers

Details