Download the PHP package madmikeyb/neutron without Composer

Neutron Framework

Neutron is a lightweight PHP micro-framework built with a focus on simplicity, modularity, and flexibility. It leverages modern PHP libraries for routing, templating, and logging to create a clean and efficient development experience.

Table of Contents

• Features
• Requirements
• Installation
• Directory Structure
• Usage
  • Running the Application
  • Routes
  • Controllers
  • Handling Request Methods and Parameters
  • GET Parameters
  • POST Parameters
  • PUT and PATCH Requests
  • DELETE Requests
  • Templates
  • Logging
• Working with Console Commands
  • Setting Up Console Commands
  • Auto-Loading Commands
  • Registering a Command
  • Running Commands
  • Using Input Arguments and Options
• Generating Migrations
  • Example
• Running Migrations
• Using the ORM
  • Retrieving All Records
  • Retrieving a Single Record
  • Filtering Records with where()
  • Ordering Records with orderBy()
  • Limiting Results with limit() and offset()
  • Checking if a Record Exists with exists()
  • Inserting a New Record
  • Updating an Existing Record
  • Deleting a Record
  • Building Queries without Executing Them (with toSql())
• Debugging
• Environment Variables
• Contributing
• License
• Future Improvements

Features

• Routing: Configurable routing using league/route.
• Templating: Render templates using twig/twig.
• Logging: Powerful logging using monolog/monolog.
• Environment Variables: Manage environment configuration using vlucas/phpdotenv.
• Error Handling: Improved error pages with filp/whoops.
• Dumping: Integrated debugging with Symfony’s var-dumper.
• Console: Application Console using Symfony’s console.
• Models/Migrations/ORM: Simple Model/Migration/ORM system using PDO and basic SQL files.

Requirements

• PHP 8.2+
• Composer (for dependency management)

Installation

1. Clone the repository:

2. Navigate into the project directory:

3. Install dependencies using Composer:

4. Set up your environment variables:

   Copy the example .env file to set up environment variables:

5. Update your .env file with the necessary configuration:

Directory Structure

Usage

Running the Application

To run the application locally, use PHP's built-in server:

Visit http://localhost:8000 in your browser to see the application running.

Routes

Routes are defined in src/routes.php. Here is an example of how a route can be defined:

Controllers

Controllers are located in the src/Controller directory. A typical controller extends the BaseController and uses dependency injection for services like logging and rendering.

Example:

Handling Request Methods and Parameters

GET Parameters

To retrieve query parameters (GET) in your controller, use the getQueryParams() method from the ServerRequestInterface. This method returns an associative array of all query parameters.

Example:

If you visit https://example.com/home?foo=bar, the $foo variable will contain "bar".

POST Parameters

For POST requests (typically form submissions), use the getParsedBody() method. This method returns an associative array of all parameters sent in the body of the request.

Example:

If a form submits a POST request to https://example.com/create with a field foo having the value bar, the $foo variable will contain "bar".

PUT and PATCH Requests

Both PUT and PATCH requests are used to update resources. You can retrieve the data from these methods using getParsedBody() just like with POST.

Example:

A PUT request to https://example.com/update/1 containing data like foo=bar will allow you to access the foo value via $foo.

DELETE Requests

While DELETE requests typically do not carry data, if they do, you can use getParsedBody() to retrieve body data or getQueryParams() for URL query parameters.

Example:

For example, a DELETE request to https://example.com/delete?id=1 would allow you to access the id query parameter.

Templates

Twig templates are located in the views directory. Here's an example home.twig template:

Logging

The framework uses Monolog for logging. Log files are written to the logs/ directory. The logging level and destination can be configured via the .env file.

Example log entry:

Working with Console Commands

Neutron supports command-line operations using Symfony Console, which allows you to create and run CLI commands easily.

Setting Up Console Commands

Neutron provides a console.php file that acts as an entry point for the command-line application. You can register and manage your custom commands in the src/console.php file.

Auto-Loading Commands

Neutron also supports automatic loading of commands from the src/Command/ directory. This allows you to define commands without manually registering them in the src/console.php file.

To take advantage of this, simply add your command classes to the src/Command/ directory, and they will be automatically loaded and registered by the framework.

Registering a Command

To add a new command to your application, follow these steps:

1. Create a Command Class: Define a new command class in the src/Command/ directory by extending Symfony\Component\Console\Command\Command.

   Example Command:

2. (Optional) Register the Command: Open the src/console.php file and register the command:

Running Commands

Once the commands are defined and registered, you can run them using the console.php file in your project root:

This will execute the HelloCommand and print the message "Hello, World.".

Using Input Arguments and Options

Symfony Console also supports input arguments and options for more flexible commands.

Example with Arguments:

You can now run the command with an argument:

Generating Migrations

You can generate migrations using the generateMigration command. Migrations are used to define changes to your database schema in a structured way. Optionally, you can also create a corresponding model for each migration.

Syntax:

• <migration_name>: The name of the migration you want to create. Example: create_messages_table
• -m: (Optional) Use this flag to generate a corresponding model for the migration.

Example:

This command will create:

• A migration file in the migrations/ directory.
• A model class Message in the src/Models/ directory (if -m is passed).

The migration file will look like this:

The model class will look like this:

Running Migrations

Once you've generated migrations, you can run them using the migrate command. This will apply any new migrations to your database.

Syntax:

This command will:

• Run all pending migrations in the migrations/ directory.
• Automatically create the database file if you're using SQLite and it doesn't already exist.

Migrations are logged in logs/migrations.log for future reference.

Using the ORM

Neutron provides a simple, chainable ORM for interacting with your database. Below are some examples of how you can use the ORM to interact with your data models.

Retrieving All Records

You can retrieve all records from a database table using the all() method.

Retrieving a Single Record

You can retrieve a single record based on a condition using the where() method combined with one() or get().

Alternatively, you can use find() to retrieve a record by its primary key (e.g., id).

Filtering Records with where()

You can filter records using the where() method and chain multiple conditions.

You can also use operators with the where query. The default, if one is not passed, is '='. An example of a "between" query is below:

Ordering Records with orderBy()

You can order the results of a query using the orderBy() method.

Limiting Results with limit() and offset()

You can limit the number of results and skip a number of records using the limit() and offset() methods.

Checking if a Record Exists with exists()

You can check if a record exists by using the exists() method.

Inserting a New Record

You can create and insert a new record using the save() method.

After calling save(), the new record will be inserted into the database, and the primary key (id) will be automatically set on the model.

Updating an Existing Record

You can update an existing record by first retrieving it and then calling save().

The save() method will automatically update the record in the database if the model already has a primary key.

Deleting a Record

You can delete a record from the database using the delete() method.

Once the delete() method is called, the record will be removed from the database, and the primary key will be unset from the model.

Building Queries without Executing Them (with toSql())

If you want to see the SQL query that would be executed without running it, you can use the toSql() method.

Debugging

Enable debugging by setting APP_DEBUG=true in your .env file. This will enable error pages with detailed stack traces, powered by Whoops.

Environment Variables

Environment variables are managed using phpdotenv. You can define custom environment variables in your .env file.

Contributing

Feel free to open an issue or submit a pull request if you find any bugs or want to add new features. Contributions are always welcome!

License

This project is licensed under the BSD 2-Clause "Simplified" License.

Future Improvements

• Middleware Support: Adding middleware for request and response handling.
• Session Management: Integrating session handling for stateful applications.
• Advanced Error Handling: Configurable error handling for production environments.