Concepts

Last updated: August 12th, 2023
Release:

Stoic:PHP aims to be as simple as possible, but there are still some concepts we use in our codebase that may seem foreign to those new to the framework. Here we'll go through our 'unique' concepts in a little detail so that the rest of our documentation won't contain any surprises. It's important to note, however, that these concepts are simply suggestions for working with Stoic:PHP and by no means are they required in order for you to take advantage of the system.

Classes

Classes, which by default live within the ~/inc/classes/ directory and have the .cls.php file extension, tend to be code classes which describe single entities within a codebase. As an example, you might have the following classes in your classes directory:

Notification.cls.php - A class representing a single notification in the system
Record.cls.php - A class representing a single record in the system

Though both of these classes are different, they are similar in the sense that each of them represents a single piece of information.

All files inside the ~/inc/classes/ directory with the .cls.php extension are automatically included with every load of the Stoic:PHP core system.

The directory and extension values can be changed by altering the classesPath and classesExt settings in your siteSettings.json file.

Repositories

Repositories, which by default live within the ~/inc/repositories/ directory and have the .rpo.php file extension, tend to be code classes that provide operations on one or more code classes. For example, you might have the following classes in your repositories directory:

Notifications.rpo.php - Provides mass operations for Notification classes/objects
Records.rpo.php - Provides mass operations for Record classes/objects

In this case, both of these repository classes would provide methods such as Notifications::getAll() or Records::getAllPublished(). Both examples are focused on operations that involve multiple instances of their associated classes.

All files inside the ~/inc/repositories/ directory with the .rpo.php extension are automatically included with every load of the Stoic:PHP core system.

The directory and extension values can be changed by altering the reposPath and reposExt settings in your siteSettings.json file.

Utilities

Utilities, which by default live within the ~/inc/utilities/ directory and have the .utl.php file extension, are code files that serve more generic purposes that don't seem to fall within the categories of either classes or repositories. For example, you might have the following classes in your utilities directory:

JiraTicket.utl.php - Provides class to submit/read tickets to/from a JIRA instance
BuildMenu.utl.php - Provides code that runs every time to build a menu structure

Each of the above files provides very different functionality, but functionality that is important to always have available when processing requests in a Stoic:PHP instance. Sometimes these are classes, sometimes they are simply code that needs to be executed in the global scope, but either way they are important enough to always include.

All files inside the ~/inc/utilities/ directory with the .utl.php extension are automatically included with every load of the Stoic:PHP core system.

The directory and extension values can be changed by altering the utilitiesPath and utilitiesExt settings in your siteSettings.json file.

Entry-Points

Entry-points are simply the way we refer to files that load the Stoic:PHP core system and intend to serve a request. They are at your control, so they can exist anywhere you like, do whatever you like, and follow whatever structure you prefer. For example, your project structure may look like:

~/inc/classes/
~/inc/repositories/
~/inc/utilities
~/index.php
~/login.php
~/register.php

The ~/index.php, ~/login.php, and ~/register.php files are all considered "entry-points" in Stoic:PHP, assuming they all have - at minimum - the following code:

<?php

	require("vendor/autoload.php");

	use Stoic\Web\Stoic;
	$stoic = Stoic::getInstance("./");

Load Order & Settings

Concept files are loaded in the following order by Stoic:PHP:

Classes
Repositories
Utilities

The following settings are available in your siteSettings.json to customize how we handle concept files:

"classesExt" - File extension for class concept files
"classesPath" - Directory path for class concept files
"includePath" - Directory used as root directory for concept file paths
"reposExt" - File extension for repository concept files
"reposPath" - Directory path for repository concept files
"utilitiesExt" - File extension for utility concept files
"utilitiesPath" - Directory path for utility concept files

Next Up

Continue to read about our components or visit the Table of Contents.