Osm Framework
Version 0.15 ∙ 1 minute read
Getting Started
Introduction
Osm Framework is an open-source, insanely fast, unprecedentedly extensible, and fun to work with PHP 8 framework for creating modern Web applications. It's built on top of tried and tested Symfony and Laravel components.
Installation
Once PHP 8, Node and Gulp are installed, create new projects quickly using the command line.
Command Line Aliases
Install and use osm
, osmc
, osmt
and osmh
command line aliases for faster command typing.
Project Structure
After you got a project up and running, you may notice that there is a lot of directories and files in the project directories. While you'll spend most of your time in src/
and themes/
directories, it's worth knowing what's all the other stuff is about.
Configuration
Configure the project settings, such as language, theme, database and search index connection details, logging, and other, in the settings.{app}.php
file. Put machine-specific settings into the .env.{app}
file. Copy and adapt ready-to-use examples from this document.
Web Server
Run your application under a Web server - a program that browsers actually communicate with. For development, consider using native PHP Web server. On a production server, use Nginx, although you may use it locally, too.
Writing PHP Code
Computed Properties
Computed properties are one of Osm Framework pillars. They help to execute code only once, and only if it's actually needed. Computed properties control object serialization and caching. They provide meaningful insights into class interdependencies. Finally, computed properties are easy to test.
Modules
Modular software development is a well-known practice of dividing your application into several modules, each doing one thing, and doing it well. It increases readability and simplifies maintenance, as application concerns are fully separated from one another, easier to reason about, and to debug.
Modular development also encourages reuse. It's like a puzzle. Using one set of modules, you'll get an e-commerce application, using another set of modules - you'll get a blog application.
Dynamic Traits
Using dynamic traits, customize anything. Inject your code in the beginning, in the end, or instead of any standard method. Even more, add new properties and methods to the existing standard classes.
Application
In Osm Framework, an application is a set of modules that you run as a whole. There are several applications defined in the project, each having its own PHP class. Mostly, deal with the main one, Osm\App\App
. Beside the class name, every application also has a name, the main one is named Osm_App
.
Access the current application object, and the main parts of Osm Framework, via the global $osm_app
object and its properties. Add your own long-living objects there. Run an application using its HTTP or console entry point, or using Apps::run()
.
Hint Classes
When dealing with plain PHP objects, be it some data read from a JSON, from a database record, or from a configuration file, use hint classes. A hint class is a class that is never directly instantiated. Instead, it provides symbol information to the IDE such as PhpStorm. With this information, the IDE helps you avoid typing error, makes you faster using code completion, and provides contextual help.
Reflection
PHP reflection is great. However, it comes with limitations: there is no efficient way of enumerating all descendants of a certain class, and it doesn't work with @property
declarations. Osm Framework addresses these limitations, and provides a very fast reflection API that powers its metaprogramming features.
Testing
Write unit tests. They are additional work, but it's worth it. Osm Framework comes all prepared for writing pure PHP tests, database tests, search tests, functional tests, tests using headless browser. Also, consider running the test suite after every push.
Creating Web Applications
Request-Response Loop
Divide your application into areas, typically, front, admin and API areas. Think through all possible requests your application can receive from a browser, and implement regular or dynamic routes that return proper responses. Apply advices that alter request processing globally, or within a specific area.
Themes And Assets
Out of the box, Osm Framework support multiple themes. It means that you can completely change look and feel of the website by changing a single setting - the current theme name.
A theme is basically a named collection of assets - Blade templates, CSS styles, JavaScript files, images, and other files that render the website. Theme assets are collected and built using gulp
and gulp watch
commands.
Blade Templates
Creating Console Applications
Processing Data
Migrations
Database
Search
Full-text search and layered navigation is a common feature for e-commerce applications. It's also used in this blog. Actually, it makes browsing any non-trivial data better. Under the hood, search and layered navigation interact with ElasticSearch, or other search engine, and this article describes how.
Writing JavaScript Code
Classes
Controllers
Testing
Other Features
Logging
Osm Framework uses Monolog library for logging. Use standard loggers defined in the $osm_app->logs
object, or add your own. Control logging in the settings.{app_name}.php
and .env.{app_name}
files.