README

Stworzony z miłością by dostarczać radość i zadowolenia z każdym pisanym fragmentem Twojej wymarzonej aplikacji.
By zacząc potrzebujesz ok. 3 minut. Storm został zaprojektowany tak by zapewnić niski próg wejścia i przejrzystość API by stał się intuicyjny. Najprostrza aplikacja składa się z 4 linijek kodu.
Jednocześnie oferuje bogactwo funkcjnalności zachowując przy tym minimalizm składni i rozmiaru. Całość ma 100KB.

Easy to learn (the simplest app has four lines)
Small footprint (100Kb, no dependencies)
Blazing fast
Built-in dependency injection container
Built-in middleware support
Built-in CQS (command query separation)
Built-in event dispatcher
Built-in multilingual support
Built-in authentication and authorization system
Built-in logger
Built-in class autoloader with scanning source code (detects automatically controllers)
Built-in path alias system ('@templates/homepage.php' refers to /your/project/dir/templates/homepage.php)
Built-in mature view system using pure PHP, child views can control the content of the master layout (adding CSS/JSS scripts or changing the title)
Built-in validation
Built-in forms
Build-in mailing (i18n, SMTP client)
Support CLI tasks (define tasks and run them from the CLI)
Support for running the controller from CLI
Support e2e tests with PHP CLI (test automatically your entire backend stack from PHPUnit easily)
Support error customization
Support middleware (You can put code in the pipeline before and after the request is handled)
Support Docker out of the box
Support PHP8 and greater
Works with StormPHP Queries

Hello World

require 'vendor/autoload.php'
$app = App::create();
$app->addRoute('/', function() { return "hello world";});
$app->run();

Przykładowa aplikacja

Dodać opis i link do StormWord

Quick start

Instalacja

Istnieją dwa sposoby instalacji Storm. Przy pomocy Composera lub sciągnięcie paczki ZIP z kodem i dołaczeniem pliku autoload z frameworka.

Composer

By zainstalować przy pomocy Composera użyj komendy

composer require stormmore/framework

w pliku index.php dodaj plik autoload

require '../vendor/autoload.php';

Standalone

Jest to wydajniejsze rozwiązanie niż paczka Composera.
Sciągnij paczkę ZIP, rozpakuj katalog src i dodaj plik autoload z katalogu src

require 'YOUR/PATH/TO/STORM/src/autoload.php';

Pierwsza aplikacja

Link do tutorialu tworzenia aplikacji od A do Z.

Dokumentacja

Designed to be intuitive as scratching your nose but there is some things you should know.

Zanim zaczniesz

Zapewne spotkałeś się już z jakimś frameworkiem MVC w PHP ale ten posiada kilka unikalnych cech o których powinieneś wiedzieć.

Skanowanie plików
Storm skanuje pliki aplikacji w celu znalezienie interesujących go klas i zapisuje je.

Nie robi tego kiedy środowisko uruchomieniowe jest zdefiniowane jako produkcja. Na produkcję należy dostarczyć plik .cache wraz z kodem.

Tip

Na środowiskach deweloperskich w przypadku nie odnalezienia klasy bądź routingu zanim zostanie wyrzuconyh bład Storm skanuje pliki.
W ten sposób możesz płynnie dodawać klasy i zmieniać nazwy bez potrzeby usuwanie ręcznie pliku.

Ładowanie klas
Storm w pierwsej kolejnści sprobuje załadować Twoje klasy na podstawie użytego namespacu.
W przypadku

use Infrastructure\Images\Resize

Sprobuje załadować klasę Resize z pliku w katalogu src/infrastructure/images/resize.php.
Jęśli nie znajdzie klasy sprobuje wyszukać klasy Infrastructure\Images\Resize w pliku .cache z przeskanowanymi klasami.

Routing
Przez zastowanie skanowania plików PHP nie trzeba rejestrować w kodzie kontrolerów. Są one odnajdywane przez atrybut Routing

Middleware
Cały framework składa się z łańcucha middlewarów wywoływanych jeden po drugim od początku żądania aż do odpowedzi.
Istnieje kilka predefiniowanych middleware które dodaje obsługę ustawien itp.
Możesz dodać własny middleware i przerwać wykonywanie w dowolnych momencie i zwrócić własna odpowiedż np. kiedy użytkownik jest niautoryzowany.

Aliasy
Storm korzysta z wewnętrznego systemu aliasów. Alias zaczyna się od znaku @ i tak możemy zdefiniować scięzkę do szablonów

$app->addMiddleware(AliasMiddleware::class, [
    '@templates' => "@/src/templates"
]);

W definicjach sciężek @ odnosi się do katalogu projektu.
W ten sposób można łatwo utworzyć wiele szablonów aplikacji.

Konfiguracja aplikacji
Nie jest wymagana ale jeśli zamierzasz zbudować coś większego napewno będziesz chciał dodać własną.
W przypadku nie podania wszystkie odnoszą się do katalogu w którym jest wykonywany skrypt.

$app = App::create(directories: [
'project' => '../', //project directory, alias `@` refers it
'source' => '../src', // source directory, it will be scanned for controllers, tasks, etc. 
'cache' => '../.cache', // file with written cache file
'logs' => '../.logs' // log directory
]);

Przykładowa struktura katalogów\

my_app_made_with_love 
├── .cache/
├── .logs/
├── public_html/
│   ├── index.php
│   ├── app.css
│   └── app.js
├── src/
│   ├── MyController.php
│   ├── Database.php
│   ├── templates/ 
│   │   └── view.php
└── README.md

.cache katalog z plikami cache
.logs logi aplikacji
public_html katalog do udostępnienia przez serwer na zewnątrz. Prócz index.php nie powinno tu być żadnych innych plików php

Konfiguracja środowiska\

Storm ładuje informacje o środowisku z pliku env.init znajdującego się w katalogu projektu.
Na każdym ze środowisk powinien być osobny plik.\

Przykładowa plik konfiguracyjny

environment = development
logger.level = info

Obsługa żądań

Obsługa żądania w Storm odbywa się na trzy sposoby.

Jako funkcja definiowana w klasie app

$app->addRoute('/', function() { return "hello world";});

Jako plik statyczny

$app->addRoute('/files', '@/src/static/files.php');

Plik statyczny ma dostęp do żadania poprzez obiekt request.
Przykładowy plik

/** @var Request $request */
if ($request->isPost()) {
    ...
}

Przez kontroler

Kontroler

namespace src\App;

use Stormmore\Framework\Mvc\Attributes\Controller;
use Stormmore\Framework\Mvc\Attributes\Route;
use Stormmore\Framework\Mvc\View\View;

#[Controller]
readonly class HomepageController
{
    #[Route("/")]
    public function index(): View
    {
        return view("@templates/homepage");
    }
}

Kontroler powinien być w dowolnym katalogu lub podkatalogu src i być oznaczy za pomocą atrybutu Controller.
Url definiuje atrybut Route.

Wstrzykiwanie zależności

#[Controller]
readonly class HomepageController
{
    public function __construct(private Request $request) {}
    
    #[Route("/")]
    public function index(): View
    {
        return view("@templates/homepage");
    }
}

By wstrzyknać zalezność należy ja zdefiniować w konstruktorze kontrolera i zostanie utworzona samoistnie.

Typ żadania

#[Route("/")]
#[Get]
public function index(): View
{
    return view("@templates/homepage");
}

Typ obsługiwanego żądania definiuje za pomoca atrybutów Get, Post, Put, Patch, Delete.

Parametry żadania

#[Route("/article")]
public function article(string $title, int $id): View
{
    return view("@templates/homepage");
}

Obsługiwany url /article?title=awesome-phg-tool&id=1.\

Możesz definiować domyśle wartości parametrów

public function article(string $title = "default title", int $id = null): View

Path parameters

#[Route("/article/:title/:id")]
public function article(string $phrase, int $id)
{
    ...
}

Obsługiwany url /article/awesome-php-tool/1

Odpowedzi kontrolera

Prócz widoku kontroler może zwrócić

Redirect

#[Route('/signout')]
public function signout(): Redirect
{
    return redirect('/');
}

Przekierowanie pod /

#[Route('/finish-order')]
public function finishOrder(): Redirect
{
    return back('/');
}

Przekierowanie na poprzednią stronę lub pod podany adres jeśli nie ma nagłówka Referer

Obiekt który jest zwracany jako JSON

#[Route("/get-product")]
public function getProduct(): object
{
    return new Product();
}

Wartość (liczba, string)

#[Route("/hello-world")]
public function getValue(): mixed
{
    return "hello-world"
}

Żądanie

Obiekt request reprezentuje żadanie. Daje interfejs do argumentów żądania, pól POST jak i plików.

Widok

Widoki w Storm są zwykłymi plikami PHP ale oferuję znaczeni więcej niż zwykły plik z HTML ponad to są szybkie bo nie potrzebują kompilacji.

Układ strony

Zazwyczaj aplikacji posiada na stale zdefiniowany nagłowek i stopkę a zmienia się zawartość. Niezmienianlną część nazywamy układem.

<?php 
/** @var View $view */
use Stormmore\Framework\Mvc\View\View; 
?>
<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" href="/public/style.css" >
    <?php
        $view->printCss();
        $view->printJs();
        $view->printTitle("StormApp");
    ?>
</head>
    <body>
        <main>
            <div style="width: 1024px; margin:0 auto">
                <?php print_view("@templates/includes/header"); ?>
                <?php echo $view->content ?>
            </div>
        </main>
    </body>
</html>

Poprzez dostęp do obiektu $view klasy View można obsłużyć szablon.
printCss i printJs wyświetlaja zasoby zdefiniowane w widoku podrzędnym. Jest to przydatne kiedy chcesz dodać plik JS i CSS w nagłówku dla konkretnych widoków. W ten sposób pobierane są tylko potrzebne zasoby.
printTitle wyświetla tytuł z podstrony bądz podany jeśli go nie ma. view->content wyświetla podstronę.

Szablon

<?php
use Stormmore\Framework\Mvc\View\View;
/** @var View $view*/
$view->setLayout('@templates/includes/layout');
?>

<h2>Success!</h2>
It's your first template. 
</br>

setLayout służy do definiowaniu układu szablonu

Kontroler

#[Route("/product")]
public function getProduct(): View
{
    return view('@templates/product')
}

Wystarczy zwrócić scięzkę do szablonu.

Wiele szablonów

Podmień scięzke dla aliasu by zmienić cały look and feel aplikacji

$app->addMiddleware(AliasMiddleware::class, ['@templates' => "@/src/templates/white"]);

$app->addMiddleware(AliasMiddleware::class, ['@templates' => "@/src/templates/black"]);

Możesz napisać własny middleware ktory będzie tworzył alis dla każdego użytkownika osobno.

Helpery

print_view sluży do printowania cząstki html.

Konfiguracja

By uzyć konfiguracji należy dodać middleware do aplikacji wraz ze scieżką do pliku

$app->addMiddleware(ConfigurationMiddleware::class, ['@/settings.ini']);

Czytanie konfiguracji

#[Controller]
readonly class TestController
{
    public function __construct(private Configuration $configuration) { }
    
    #[Route("/print-env")]
    public function printEnv(): string
    {
        return $this->configuration->get("environment");
    }
}

Internatiolization (i18n)

By właczyć internacjonalizacje dodaj middleware

$app->addMiddleware(LanguageMiddleware::class);

Wymaga on wpisów w konfiguracji (możesz umieścić je w settings.ini bądz env.ini)

i18n.multi_language = true
i18n.default_language = en-US
i18n.languages = en-US, en-GB, fr-FR, de-DE, pl-PL
i18n.cookie.name = locale
i18n.translation.file_pattern = @/src/lang/%file%.ini
i18n.culture.file_pattern = @/src/lang/culture/%file%.ini

stormmore / framework

Maintainers

Details

README

Hello World

Przykładowa aplikacja

Quick start

Instalacja

Composer

Standalone

Pierwsza aplikacja

Dokumentacja

Zanim zaczniesz

Obsługa żądań

Kontroler

Wstrzykiwanie zależności

Typ żadania

Parametry żadania

Path parameters

Odpowedzi kontrolera

Redirect

Obiekt który jest zwracany jako JSON

Wartość (liczba, string)

Żądanie

Widok

Układ strony

Szablon

Kontroler

Wiele szablonów

Helpery

Konfiguracja

Czytanie konfiguracji

Internatiolization (i18n)