Download the PHP package lumax/luma without Composer

Welcome to Luma, an opinionated PHP framework.

The information found below may be outdated. This section remains until updated documentation is completed.

• Installation
• Get Started
  • Optional: Using PHPEnv + Docker
• Configuration
  • Routes Configuration
  • Services Configuration
  • The .env File
• Controllers
  • The LumaController
• Templating Engine
• The Database Component
  • Create Database Tables
  • Define Aurora Models
  • Using Aurora Models
  • Create
  • Read
  • Update
  • Delete
  • The Query Builder
• Additional Features
  • HTTP Client
  • Caching
  • Logging

Installation

To begin using Luma, you can effortlessly set up the framework using Composer. Simply execute the following command in your terminal:

Get Started

When your project is installed via the create-project command, Luma runs post-setup commands to clean up your project structure and help you get started as quickly as possible. This installs all required PHP libraries and NPM dependencies inside your project, meaning your new Luma app can be run straight away.

Optional: Using PHPEnv + Docker

This section provides information on setting up a development environment for your Luma application. If you already have a PHP development environment or are comfortable running PHP applications locally, you can skip this section.

Luma and PHPEnv go hand-in-hand to provide a smooth development experience, allowing you to start building and debugging as quickly as possible.

Note: PHPEnv requires Docker Desktop to be installed on your system.

To download and install PHPEnv, run the following command to install the package globally:

Next, ensure Docker Desktop is running.

Now, creating and running a new Luma app inside PHPEnv is as simple as running the following commands:

The phpenv build command will display a local URL for your application. Click or copy/paste the URL into your browser to visit your new Luma app. Setup complete.

Refer to the PHPEnv README for more detailed information about the library.

Configuration

Routes Configuration

Define your application's routes in the config/routes.yaml file. Here's an example route definition (which is included in your application by default):

In the example above, we've defined a route for the root path, directing it to the index method of the App\Controller\AppController - check out your applications routes file and controller to see how these work.

In addition, we can also define dynamic routes:

Services Configuration

Service definitions are stored in config/services.yaml. Below is an example service configuration:

Services can currently be injected into the constructor of other services using the @service_id argument as shown above. Services can also be injected into controller constructors. Services cannot currently be injected into controller methods.

The .env File

Luma uses the vlucas/phpdotenv package to allow you to handle environment variables. Your new Luma app will include some default environment variables, but you are free to use this file to define any custom environment variables your application might need.

Variables within this file can be accessed within your application by accessing the $_ENV array.

Currently, your default .env contains a single used variable: ENVIRONMENT=development. Optional database credentials are provided but commented out by default. Uncomment these values and supply your database credentials to allow your app to connect to and work with a database.

Controllers

We have briefly touched upon controllers in the routes configuration section where we learned how to define our routes. This section aims to expand upon that and provide an overview of controllers within a Luma application.

The LumaController

The LumaController is the base class for all controllers within a Luma application. A simple "Hello, world!" LumaController might look something like this:

Next, we can define a new route that uses this method.

This will ensure that all requests to /hello-world within your application will now be handled by the HelloWorldController::sayHelloWorld method. The respond method will echo the text (Hello, world!) to the page when this endpoint is reached.

The LumaController also allows us to return a JSON response, great for building API's. This allows us to serialize arrays or objects. To return a JSON response from your controller methods, use the built-in LumaController::json method:

Templating Engine

Luma uses the Latte templating engine in order to render dynamic HTML content. We can use the render method in the LumaController to render a view. This method takes two parameters: the name of the template file (with or without the .latte extension) and an array of parameters to pass to the template.

Here's an example of how you might use it in a controller:

In this example, the index method of the ExampleController is rendering the index.latte template and passing in an array of data. This data can then be accessed in the index.latte template file like so:

In this template, {$title} and {$description} are placeholders that get replaced with the corresponding values from the $data array passed to the render method.

Remember to place your .latte files in the views directory of your Luma project. The render method looks for templates in this directory by default.

The Database Component

Luma allows you to easily connect to and interact with a database within your application, powered by the lumax/aurora-db library. To start using a database with your Luma app, uncomment the DATABASE_ variables in your .env file.

The DATABASE_SCHEMA and DATABASE_DRIVER variables are optional - if you wish to access all Schemas within your database then you can omit the SCHEMA variable. If your application uses a MySQL database, there is no need to include the DRIVER variable.

Create Database Tables

To start, define your database tables and execute in your preferred console. Let's define a table where our users will be stored:

This creates a simple test tblUser table in the User schema.

Now, let's create a table that references the User.tblUser table:

The Aurora Model

Next, we can create Aurora models to interact with the new database tables we just created. Starting with the User:

This basic Aurora model is already quite powerful, allowing you to perform CRUD operations directly against your database table.

Here is an example of the Aurora model we could create for our Article table:

Using Aurora Models

As you can see from the examples above, an Aurora model is small, providing a simple representation of our database rows in PHP. Before I begin detailing the various ways you can use your Aurora classes to interact with the database, it's important to understand a few important rules:

• All classes extending Aurora MUST have a primary identifier, indicated by the #[Identifier] attribute.
• All primary identifiers MUST be protected (or public, but not recommended).
• All properties that you wish to map to a database column MUST include a #[Column($name)] attribute.

Create

We can easily create new records in our database using the create method:

Read

We can easily retrieve records with the find and findBy methods:

Update

The save method also allows us to update existing records:

Delete

We can delete existing records really easily too:

The Query Builder

In addition to the methods described above, Luma + Aurora DB allow you to build more complex queries thanks to the built-in query builder. We start by building up our query:

The above snippet executes SELECT * FROM Core.tblArticle. The select method allows you to specify the columns you wish to return and map. You can specify the name of the property or column:

Note: The query builder will always return the primary identifier, so you do not need to specify this explicitly.

We can also specify conditions with the whereIs, whereNot, whereIn and whereNotIn methods. These can be chained, in which case they are automatically converted to AND:

We can also add orderBy and limit conditions:

Additional Features

HTTP Client

Luma provides a built-in HttpClient class to help simplify HTTP requests within your PHP. Using it is quite straightforward:

Caching

Luma optimizes performance by caching views in the cache/views directory, providing a simple way to reduce the overhead of rendering templates on each request.

Logging

Luma integrates with the tracy/tracy package for straightforward logging. Logs are stored locally in logs/info.log, allowing you to keep tabs on essential information about your application's behavior. Here's how you could use this in your application: