ian-maurmann/pith-framework

Pith Framework

Pith Framework

Website | Release Notes

---

⚠️ (Not ready yet) ⚠️

---

This framework is a work-in-progress proof-of-concept.

If you're looking for a framework to use for your project, please check out: Symfony, Laravel, Zend / Laminas, Slim, Cake, or CodeIgniter instead.

---

Install

• Open the terminal and navigate to the directory your project will be in.
• Install Composer. Follow the instruction at Download Composer.
• Require Pith Framework from Composer:

php composer.phar require pith/framework

Nice to haves:

Add a symbolic link to composer.phar

ln -s ./composer.phar ./composer

Copy the Pith Command Tool into the directory

cp vendor/pith/framework/pith .

Copy the Migration runner into the directory

cp vendor/pith/framework/mig .

Make a symbolic link to Pest inside the directory

ln -s ./vendor/bin/pest ./pest

Make a symbolic link to PHPStan inside the directory

ln -s ./vendor/bin/phpstan ./phpstan

ln -s ./vendor/bin/phpstan ./stan

---

⚠️ (Not ready yet) ⚠️

---

Workflow:

.

(Actual flow)

---

pith-framework's Issues

TODO: Dispatcher Object

TODO: Dispatcher Object

• Child of App.
• Runs on the "Operation Level" after Router.
• Receives a Route to run.
• Runs the Route's injectors / actions / preparers / views: the "Dispatch Level"

INITIATIVE - Engine Workflow Initiative

Engine Workflow Initiative Roadmap for 0.8

---

General

Fixup:

• Add PhpDoc comments
• PhpDoc comments in PhpStorm can display pictures now. Add documentation pictures.

Refactor:

• Refactor objects to use the App Reference Trait.

Pith Info

Add:

• Meta Object (Internal, with framework version info, legal info.)
• Info Object $this->app->info (External, with methods that talk to Meta Object, but also app info, and info from the pith.json file.)

Edit:

• The Info Object should be accessible from $this->app->info

Cleanup / refactor at the end:

• Remove the Version Trait

Config

Add:

• Add simple Constants file.
• New Config system.

Cleanup / refactor at the end:

• Remove the current Config.
• Remove the Config Profiles.

Engine

Add:

• Engine Object $app->engine & $this->app->engine
• Engine State Machine Object (Dispatching was too interconnected for using states)
• Engine State Object? (Or use PHP8 enum? Or a simple string?) (n/a)

Framework Startup:

• Add new startup method $app->engine->start();

Workflow

• State Machine should have methods like enterRouting( ), and enterDispatching( ) (n/a)

Cleanup / refactor at the end:

• Remove the Startup Trait
• Remove the Run Trait

Routing

Add to Engine

• Do routing with FastRoute (Figure out how to keep our 2-level routing, and how to dynamically add/remove routes. Cache routes, to array?)

Cleanup / refactor at the end:

• Remove the current Router. --- (Router is all the new Routing implementation with FastRoute now)

Dispatch

Add to Engine

• Add new cleaned-up Dispatcher. (Added new functions to Dispatcher)
• Instead of Controller Objects with action( ) and preparer( ) functions, use Action Objects and Preparer Objects.

Cleanup / refactor at the end:

• Remove the current Dispatcher (Added new functions to Dispatcher)
• Cleanup Dispatcher.

Error Reporting

Add

• Add "PithException" exception
• Add special Monolog logging for Pith Exceptions, ex: $e->logMysqlConnectionFailure, for when services catch exceptions for well-known problems.

Cleanup / refactor at the end:

• Remove the current Problem calls.
• Remove the Problem trait.
• Remove the Problem Handler

---

Appendix A

Objects in 0.7.5

External

External Extendable:

• Pith Access Level
• Pith Controller
• Pith Query

External Interfaces

• Pith App Interface
• Pith Config Interface
• Pith Controller Interface
• Pith Module Interface
• Pith Router Interface

External Objects

• Pith Access Control
• Pith App
• Pith Config
• Pith Dispatcher
• Pith Request Processor
• Pith Router

External Traits

• Pith Problem Trait
• Pith Run Trait
• Pith Startup Trait
• Pith Version Trait

Internal

Internal Objects

• Pith Access Level Factory
• Pith App Helper
• Pith Problem Handler
• Pith Problem List
• Pith Request Helper
• Pith Route
• Pith State Enum
• Pith State Machine
• Pith String Utility

Internal Traits

• Pith App Reference Trait

---

Appendix B (WIP)

Current Objects in 0.8+ (WIP)

External

About:

• Pith Meta

External Extendable:

• Pith Access Level
• Pith Action
• Pith Controller
• Pith Conversion
• Pith Pack
• Pith Preparer
• Pith Query
• Pith Route
• Pith Route List
• Pith View Requisition
• Pith Workflow Element

External Interfaces

• Pith App Interface
• Pith Config Interface
• Pith Controller Interface
• Pith Module Interface
• Pith Router Interface

External Objects

• Pith Access Control
• Pith App
• Pith Config
• Pith Converter
• Pith Database Wrapper (Moved)
• Pith Dispatcher
• Pith Engine
• Pith Exception
• Pith Info
• Pith Request Processor
• Pith Responder
• Pith Router

External Traits

• Pith Problem Trait
• Pith Run Trait
• Pith Startup Trait
• Pith Version Trait

Internal

Internal Objects

• Pith Access Level Factory
• Pith App Helper
• Pith Array Utility (Moved)
• Pith Database Wrapper Helper (Moved)
• Error Utility (Moved)
• Pith Escape Utility
• Pith Expression Utility
• Pith Problem Handler
• Pith Problem List
• Pith Request Helper (Converted to URI Utility)
• Pith Route
• Pith Rowset Array Utility (Moved)
• Pith State Enum
• Pith State Machine
• Pith String Utility
• Pith URI Utility (From old Pith Request Helper)

Internal Traits

• Pith App Reference Trait
• Pith Get Object Class Directory Trait

Internal Workflow Access Levels

• World Access Level

Internal Workflow Elements

• Empty Action
• Empty Preparer
• Empty View Requisition

Misc. Files

• Index Front Controller
• Constants file
• Routes file
• .serve.php file

Misc. Plugins

• Command Tool
• Database Wrapper (Moved)
• Internal Access Levels
• Internal Utilities (Moved)
• PHTML View Adapter
• PHTML View Adapter 2
• Pith-dot-json

---

Appendix C (WIP)

List of Additions and Cleanups (WIP)

• Added 0.8 ToDo List.
• Added Engine Workflow Initiative Roadmap for 0.8 (This file).
• Added constants, Added Pith Info.
• Added Engine.
• Added Routes file.
• Added routing with FastRoute to replace old routing.
• Added new dispatching methods for Action object to Preparer object workflow.
• Added a 2nd .phtml adapter with new View logic

---

Appendix D (WIP)

Current Objects refactored to use the App Reference Trait

(All Done)

---

Appendix E (WIP)

Current Objects with PhpDoc comments

(All Done)

---

Appendix F (WIP)

Current Objects with images for PhpDoc comments (TODO)

(TODO)

---

Next Steps

• Database workflow
• Unit Testing
• Integration Testing
• Database Migrations
• Access Levels

TODO: Access Levels

TODO: Access Levels

Access Level:

• Is used by the Access Control ✔
• Is listed in Route
• Is checked by Dispatcher at the beginning of running the "Dispatch Level" ✔
• Dispatcher talks to Access Control, Access Control talks to Authenticator. Access Control gives the Dispatcher a Yes/No on running the items listed in the Route. ✔

There will be default Access Levels, i.e. World✔, User, Admin, Dev, that 3rd-party modules/packages/libraries/plugins can default their pages to.

TODO: App Object

TODO: App Object

• Main object to interact with
• Declared in Front Controller
• Should be accessible inside injectors / actions as $app
• First runs the framework setup, the "App Level", then runs the "Operation Level"

(Basically fill the role of the old $pith variable in the framework from 0.1 to 0.5)

TODO: Config Object

TODO: Config Object

• Process the config files
• Stores the config info: base path, database info, etc
• Child of the App Object
• First runs on the "Operation Level", but stays alive incase it is needed
• After the "App Level" is run, the App runs the "Operation Level", the Config Object runs first

TODO: Injectors

TODO: Injectors

Every Injector:

• Lives inside a package or module.
• Is listed in a Route.
• Is run by the Dispatcher after the Access Level.
• The Injector's job is to declare objects that are passed to the Action.
• Can declare new objects.
• Can pull objects from Container.
• Pushes to Action.

EPIC - Basic Shared UI, Example site

Get started on basic version of the Shared UI,

Example site

TODO: Parameters in Rout Path

TODO: Parameters in Rout Path

i.e.

example.com/something/1234

example.com/something/1234/something-else

or else use another library for parsing routes

INITIATIVE - Authentication & Authorization with Shared UI Initiative

Authentication & Authorization with Shared UI Initiative Roadmap for 0.8.4+

---

General

Shared Infrastructure:
#19

• Add a new Shared Infrastructure Pages pack
• [x CSS using the name shared-ui as the prefix.
• Add CSS / Javascript resources for Shared Infrastructure Pages
• Use path /resources/vendor/common-libraries for libs (Ex: jquery, toastr, oxcss, hola).
• Use path /resources/framework/shared-ui/ for resources for Shared-UI js / css.
• Shared Infrastructure Layout
• New User page.
• User Login page.

Pith Panel

• Add a new Pith Panel Pages pack
• Pith Panel layout / theme
• CSS using the name pith-panel as the prefix.
• Add CSS / Javascript resources for Panel

Housekeeping

Housekeeping:

• Remove more circular refs from the App Object.

TODO: Views

TODO: Views

Every View:

• Lives inside a package or module.
• Is listed in a Route.
• Is run by the Dispatcher after the Preparer.
• The View's job is to give output, i.e. HTML / template code, or to be an End Point outputting JSON / XML / etc.
• Pulls variables from the Preparer

TODO: Database Object

Todo: Add a database object that will fill the same role as the database object before the re-write.

• Should be PDO this time, was mysqli before.
• Use Postgres?

TODO: Routes

TODO: Routes

Every Route:

• Lives in a package / module.
• Can have a "route space" it shares with other routes.
• Will need a way for the Router to map the Route to a given URL.
• Has an Access Level.
• Lists items to be run on the "Dispatch Level" by the Dispatcher: injectors / actions / preparers / views.

TODO: Router Object

TODO: Router Object

• Child of App.
• Runs on the "Operation Level" after Access Control.
• Matches the requested URL to a route.

TODO: Access Control Object

TODO: Access Control Object

• Child of App.
• Runs on the "Operation Level" after Authenticator.
• Receives the access control info (from Config? from Registry?)
• Stays alive for the Router to ask if the User/Guest is allowed to use a given route.

TODO: Authenticator Object

TODO: Authenticator Object

• Child of App
• Runs on the "Operation Level" after the Registry.
• Authenticator Object's job is to determine if the current Actor is a logged-in User or a Guest.
• Stores User / Guest info for when needed.

TODO: Preparers

TODO: Preparers

Every Preparer:

• Lives inside a module / package.
• Is listed inside a Route.
• Is run by the Dispatcher after the Action.
• Preparer's job is to get variables from the Action and format them for the View.
• Pulls from the Action.
• Pushes to the View.

TODO: Container

TODO: Container

• Need a container object for dependency injection.
• Best if it follows PSR-11
• Hopefully find a good DI / PSR-11 implementation from someone else, otherwise write-our-own.

TODO: Actions

TODO: Actions

Every Action:

• Lives in a package / module.
• Is listed inside a Route.
• Is run by the Dispatcher after the Injector.
• The Action's job is to ask the Model to perform whatever the work we want the Route / URL to do, and then pass the resulting info to the Preparer.
• Pulls variables from the Injector.
• Talks to Model.
• Pushes variables to the Preparer.

Feature - Reserved Name Utility

Utility for returning reserved names: For reserved filenames, reserved usernames, reserved subdomain names, etc.

TODO: Registry Object

TODO: Registry Object

• Child of App
• Runs on the "Operation Level" after Config
• Gets info from Config where it can find packages/modules with injectors / actions / preparers / views.
• Registry Object's job is to find injectors / actions / preparers / views when asked.
• The Registry Object is not a container.
• The Registry Object is only responsible for items that can be listed inside Routes and run by Dispatcher.
• The Registry Object is not responsible for the Model. It doesn't know about Helpers / Entities / Services / Utilities / Callers / Gateways / etc.

Story - Add new utility - Reserved Name Utility

Add new utility - Reserved Name Utility

#20