0.1.0-alpha.72

Dokumentacja.

Zainstaluj Formaku, opublikuj pierwszą stronę i zintegruj developerską wersję modułu Commerce.

Zainstaluj starter

Potrzebujesz PHP 8.4+, Composera, Node.js 22.12+ i SQLite. Przed migracją włącz rozszerzenie SQLite w PHP. Sklonuj oznaczone wydanie alfa i uruchom poniższe polecenia. Polecenie tworzące administratora uruchom osobno w interaktywnym terminalu. Wpisz hasło o długości co najmniej 12 znaków i poczekaj na potwierdzenie przed uruchomieniem polecenia demo.

git clone --branch v0.1.0-alpha.72 --single-branch https://github.com/formaku/formaku.git
cd formaku
cd apps/starter
composer install
cp .env.example .env
php artisan key:generate
touch database/database.sqlite
php artisan migrate
cd ../..
npm ci --ignore-scripts
npm run build
cd apps/starter
php artisan formaku:install
php artisan formaku:admin twoj-email@example.com
php artisan formaku:demo
php artisan serve

Otwórz ścieżkę /formaku pod adresem wypisanym przez Artisan. Zaloguj się utworzonym kontem administratora. Na świeżej instalacji polecenie demo dodaje przykładowe kolekcje i publikuje /p/start. Konta klientów utwórz osobno.

Jeśli korzystasz z AI, zaplanowanej publikacji lub powiadomień, uruchom kolejkę i harmonogram w osobnych terminalach z katalogu apps/starter.

php artisan queue:work --tries=1 --timeout=90
php artisan schedule:work

Zmień język panelu

Od alpha.16 w nagłówku panelu wybierz Polski lub English z listy Język panelu (Panel language). Przeglądarka zapamięta wybór. Nazwy kolekcji, własne etykiety pól i treści zachowają język, w którym je wpisano.

Modeluj dane i publikuj strony

  1. W builderze utwórz kolekcję treści lub danych. Nadaj polom stałe klucze, określ relacje i w razie potrzeby skonfiguruj stany i przejścia procesu.
  2. Aktywuj definicję. Dodaj rekord przez wygenerowaną listę i edytor. Rekordy treści mogą zawierać bloki tekstu, obrazów, kart i FAQ. Po zapisaniu rekordu możesz użyć bezpośredniego linku do jego edytora.
  3. Zapisz szkic i obejrzyj podgląd strony z konta mającego dostęp do panelu. Opublikuj gotową treść. Podczas edycji kolejnego szkicu witryna nadal pokazuje ostatnią opublikowaną rewizję.
  4. W historii wersji obejrzyj wcześniejszą rewizję lub przywróć ją do szkicu. Jeśli rekord zmienił się na serwerze, wykonaj kroki opisane w instrukcji rozwiązywania konfliktu zapisu.

Definicje kolekcji eksportujesz i importujesz w ustawieniach. Jeśli kolekcja ma już rekordy, zaplanuj migrację w Laravel przed usunięciem pola lub zmianą jego typu.

Przycisk Dodaj rekord i wybór kolekcji w podglądzie AI wymagają uprawnień do tworzenia rekordów i zapisu wszystkich pól wymaganych przez kolekcję.

Otwórz zapisany rekord w kolekcji treści lub danych. Adres panelu zawiera identyfikator rekordu, na przykład /formaku?record=123. Odśwież stronę, aby wrócić do rekordu, albo wybierz Otwórz rekord w nowej karcie w edytorze. Aby udostępnić link innej osobie z zespołu, skopiuj adres z przeglądarki.

Link otwiera ostatnią zapisaną wersję. Osoba otwierająca link musi zalogować się do panelu i mieć dostęp do rekordu. Jeśli rekord jest niedostępny, nadal możesz przeglądać kolekcje, do których masz dostęp.

Rozwiąż konflikt zapisu szkicu

Jeśli na serwerze zapisano nowszą wersję rekordu treści lub danych, po konflikcie zapisu Twoje zmiany pozostają w formularzu. Edytor wstrzymuje zapis ręczny i automatyczny do czasu wczytania aktualnego szkicu.

  1. W rekordzie treści wybierz Podgląd w nowej karcie, aby porównać swoje zmiany z aktualnym zapisanym szkicem.
  2. Wybierz Pobierz moje zmiany, aby zachować w pliku JSON wartości pól, które możesz edytować. Skorzystaj z pliku przy ręcznym odtwarzaniu zmian.
  3. Wybierz Wczytaj aktualny szkic i potwierdź odrzucenie niezapisanych zmian w formularzu. Po wczytaniu wersji z serwera wprowadź ponownie zmiany, które chcesz zachować, i wybierz Zapisz szkic.

W kolekcji treści lub danych wpisz fragment tytułu albo nazwy w polu Szukaj po tytule lub nazwie i kliknij Szukaj. Formaku przeszukuje wszystkie strony kolekcji, korzystając z ostatnio zapisanego szkicu i pól, które możesz odczytać. Znaki takie jak % i _ są traktowane dosłownie. Rozróżnianie wielkości liter i znaków diakrytycznych zależy od bazy danych. Wyniki wyszukiwania możesz zawęzić w polu Filtr stanu, a w kolekcjach treści także w polu Filtr publikacji. Wpisana fraza pozostaje aktywna przy zmianie strony i po powrocie z edytora. Aby ją usunąć, opróżnij pole i ponownie kliknij Szukaj.

Filtruj rekordy według stanu procesu

Jeśli w kolekcji treści lub danych skonfigurowano stany, otwórz Filtr stanu nad listą rekordów i wybierz stan. Wybór pozostaje aktywny podczas zmiany stron i po powrocie z edytora. W kolekcji treści wybierz Zaplanowane w polu Filtr publikacji, aby znaleźć nadchodzące i zaległe publikacje w wybranym stanie. Aby wyczyścić filtr stanu, wybierz Wszystkie stany.

Filtruj treści według stanu publikacji

Nad listą rekordów kolekcji treści otwórz Filtr publikacji i wybierz jedną opcję.

  • Nieopublikowane pokazuje rekordy bez aktualnie opublikowanej wersji.
  • Opublikowane pokazuje rekordy z opublikowaną wersją, również te z nowszym szkicem.
  • Z nowszym szkicem pokazuje opublikowane rekordy z później zapisanym szkicem.
  • Zaplanowane pokazuje szkice z zapisanym terminem publikacji.

Na liście etykieta Szkic oznacza rekord bez aktualnie opublikowanej wersji, a Opublikowano oznacza rekord z opublikowaną wersją. Po zapisaniu kolejnego szkicu obok etykiety Opublikowano pojawia się Nowszy szkic. Filtr publikacji działa razem z wyszukiwaniem i filtrem stanu procesu. Wybierz Wszystkie stany publikacji, aby wyczyścić filtr publikacji.

Zaplanuj lub anuluj publikację

Zapisz szkic, wybierz Datę publikacji i kliknij Zaplanuj publikację. Panel pokazuje zapisany termin w strefie czasowej przeglądarki. Wybierz Anuluj zaplanowaną publikację, aby usunąć termin i zachować szkic. Zapis kolejnej rewizji usuwa poprzedni termin. W starterze zaplanowana publikacja wymaga działającego schedulera. Przy instalacji przez Composer dodaj komendę formaku:publish-scheduled do schedulera Laravel.

Po błędzie szkic zachowuje termin. Komenda przetwarza pozostałe szkice, po czym podaje liczbę opublikowanych, pominiętych i nieudanych publikacji. Jeśli wystąpił błąd, zwraca niezerowy kod.

Na liście kolekcji treści wybierz Zaplanowane w polu Filtr publikacji, aby zobaczyć terminy od najwcześniejszego, w tym zaległe. Użyj przycisków pod listą, aby zmienić stronę. Po powrocie z edytora filtr i bieżąca strona pozostają aktywne.

Wycofaj publikację strony

Jeśli masz uprawnienie do publikowania i zapisu rekordu, otwórz opublikowany rekord w edytorze treści, kliknij Wycofaj publikację i potwierdź. Formaku zachowuje ostatni zapisany szkic i historię wersji oraz anuluje zaplanowaną publikację rekordu.

Strona znika z publicznego katalogu i mapy witryny. Do ponownej publikacji jej bieżący i wcześniejsze publiczne adresy zwracają błąd 404, chyba że danego adresu używa inny rekord. Aby ponownie udostępnić stronę, otwórz rekord i opublikuj zapisany szkic.

  1. W polu relacji w edytorze kliknij Wybierz rekordy. Wcześniej powiązane rekordy są już zaznaczone po otwarciu okna.
  2. Za pomocą pól wyboru zaznacz jeden lub kilka rekordów. Lista pokazuje do 25 rekordów na stronę i zachowuje zaznaczenia podczas zmiany strony.
  3. Kliknij Zastosuj wybór, a następnie zapisz szkic. Aby zamknąć okno i zachować poprzedni wybór, kliknij Anuluj lub naciśnij Esc.

Możesz wybrać rekordy, do których Twoje konto ma dostęp w kolekcji docelowej. Lista pomija prywatne tytuły i nazwy. Wcześniej powiązane rekordy pozostają zaznaczone po utracie dostępu. Przed zapisem usuń takie powiązanie albo odzyskaj dostęp do rekordu.

Układaj bloki w kontenerach i kolumnach

W edytorze strony dodaj kontener lub blok kolumn. W kontenerze wybierz Pionowo, aby ustawić bloki jeden pod drugim, lub Automatycznie, aby siatka dopasowała się do dostępnego miejsca. W bloku kolumn wybierz dwie lub trzy kolumny. W węższym układzie siatka użyje mniejszej liczby kolumn, a gdy miejsca jest mało, ustawi bloki jeden pod drugim.

Wewnątrz układu wybierz typ bloku i kliknij Dodaj blok do układu. Strzałkami w górę i w dół zmienisz kolejność bloków w tym układzie. Przyciskiem usuwania usuniesz blok z układu. Zapisz szkic i sprawdź podgląd w różnych szerokościach przed publikacją. Układy zapisane bez tego ustawienia nadal korzystają z automatycznej siatki.

W bloku obrazu zagnieżdżonym w kontenerze lub kolumnach wybierz publiczny obraz z biblioteki tak samo jak w bloku na głównym poziomie strony.

Korzystaj z szablonów stron

  1. Jako administrator zapisz szkic z co najmniej jedną sekcją. W części Szablony stron wpisz nazwę i wybierz Zapisz jako szablon.
  2. W tej samej kolekcji wybierz Dodaj rekord, a następnie Pokaż szablony kolekcji. Wybierz szablon i kliknij Wstaw sekcje szablonu, zanim dodasz własne sekcje do nowego szkicu.
  3. Uzupełnij tytuł i adres, dostosuj skopiowane sekcje i zapisz szkic. Gdy strona jest gotowa, wybierz Opublikuj treść.

Do użycia szablonu potrzebujesz prawa tworzenia rekordów w tej kolekcji. Szablon kopiuje do nowego szkicu wyłącznie sekcje. Edycja kopii lub usunięcie szablonu pozostawia stronę źródłową i pozostałe kopie bez zmian.

Obejrzyj zapisany szkic

Zapisz szkic i wybierz Pokaż podgląd w edytorze. Przełącz widok między komputerem (1280 px), tabletem (768 px) i telefonem (390 px). Podgląd używa tego samego renderera co publiczna strona i pokazuje tytuł oraz opis SEO zapisanego szkicu. Kolejny zapis odświeża podgląd. Wybierz Podgląd w nowej karcie, aby otworzyć go osobno.

Kliknij Powiel blok, aby wstawić kopię za wybranym blokiem na tym samym poziomie. Kopia kontenera lub kolumn obejmuje bloki wewnętrzne. Zmień kopię i zapisz szkic przed publikacją. Obrazy w kopii wskazują te same pliki w bibliotece mediów.

Kliknij Przenieś blok i wybierz Poziom strony, kontener albo kolumny. Edytor dodaje blok wraz z zawartością na koniec wybranej listy. Następnie możesz zmienić kolejność i zapisać szkic.

Kliknij Cofnij usunięcie bloku obok nagłówka Sekcje strony, aby przywrócić ostatni blok usunięty ze szkicu. Blok zachowuje zagnieżdżoną treść i odwołania do mediów. Cofnięcie działa także po zapisie automatycznym w trakcie edycji tego samego szkicu.

Od alpha.27 zmiany w zapisanym szkicu wprowadzone podczas odświeżania panelu po publikacji są zapisywane automatycznie po zakończeniu odświeżania. Zmiana pozostaje w szkicu do następnej publikacji.

Przeglądaj historię wersji

Otwórz zapisany rekord i kliknij Historia wersji. Edytor pokazuje po 25 rewizji na stronie, od najnowszej. Kliknij Następna strona, aby zobaczyć starsze rewizje, lub Poprzednia strona, aby wrócić. Podczas przeglądania historii niezapisane zmiany pozostają w edytorze.

W Historii wersji wybierz Porównaj ze szkicem przy rewizji, aby zobaczyć różnice względem zapisanego szkicu. Formaku pokazuje tylko zmienione pola dostępne do odczytu. Porównanie korzysta z zapisanych wartości i zachowuje niezapisane edycje w formularzu.

Aby przywrócić rewizję z dowolnej strony historii, zapisz bieżące zmiany, a następnie kliknij Przywróć do szkicu przy wybranej rewizji.

Obejrzyj wcześniejszą rewizję

W rekordzie treści kliknij Podgląd rewizji przy wybranej rewizji na dowolnej stronie historii. Zapisana rewizja otworzy się w nowej karcie i będzie dostępna dla kont z dostępem do rekordu w panelu. Podgląd korzysta z bieżącej definicji kolekcji i pokazuje pola, które możesz odczytać.

Gdy przywrócony szkic treści będzie gotowy, opublikuj go.

Zarządzaj biblioteką mediów

Otwórz Media w panelu. Biblioteka wyświetla do 30 plików na stronę. Jeśli stron jest więcej, użyj przycisków Poprzednia i Następna.

  1. Przy pliku wybierz Edytuj metadane.
  2. Zmień pole Nazwa pliku lub, w przypadku obrazu, wpisz opis w polu Tekst alternatywny.
  3. Wybierz Zapisz metadane.

Nowa nazwa pojawi się w bibliotece i w nagłówku Content-Disposition odpowiedzi z plikiem. Adres i zawartość pliku pozostają bez zmian. Opublikowane strony korzystające z obrazu użyją zaktualizowanego tekstu alternatywnego.

Edycja metadanych plików publicznych wymaga uprawnienia do publikacji, ponieważ zmienia publiczne odpowiedzi. W starterze to uprawnienie mają publikujący i administratorzy. Metadane plików prywatnych może edytować personel z dostępem do obszaru pracy.

Sprawdź, gdzie plik jest używany

W bibliotece mediów kliknij Użycie pliku przy pliku. Lista jest podzielona na strony i pokazuje dostępne dla Ciebie rekordy, które używają pliku w polu mediów lub w bloku obrazu, także zagnieżdżonym. Lista pomija prywatne tytuły i nazwy.

Oznaczenia Szkic i Publikacja wskazują wersje, które używają pliku. Rekord może mieć oba oznaczenia. Lista obejmuje bieżący szkic i bieżącą opublikowaną wersję.

Wybierz plik do rekordu

  1. W polu mediów w edytorze rekordu kliknij Wybierz plik.
  2. Odszukaj plik po nazwie i wybierz go. Lista pokazuje do 30 plików na stronę, w tym obrazy i PDF-y, oraz informację, czy dany plik jest publiczny, czy prywatny. Aby zamknąć okno i zachować dotychczasowy wybór, kliknij Anuluj lub naciśnij Esc.
  3. Zapisz szkic, aby zachować wybrany plik w rekordzie.

Dostęp do plików zależy od dotychczasowych uprawnień. Lista obrazów dla bloków strony pokazuje wyłącznie publiczne obrazy.

Wybierz obraz do bloku strony

  1. Otwórz blok obrazu w edytorze strony i kliknij Wybierz obraz.
  2. Odszukaj istniejący obraz po nazwie pliku lub miniaturze i wybierz go. Lista pokazuje do 30 publicznych obrazów na stronę i pomija pliki prywatne oraz PDF. Aby zamknąć okno i zachować dotychczasowy wybór, kliknij Anuluj lub naciśnij Esc.
  3. Jeśli chcesz dodać podpis, wpisz go w polu Podpis obrazu. Zapisz szkic i sprawdź podgląd przed publikacją.

Udostępniaj responsywne obrazy WebP

Formaku może tworzyć warianty WebP o szerokości 480 i 960 px z publicznych obrazów JPG, PNG i WebP bez ich powiększania. Strona korzysta z wariantów, gdy są dostępne. W razie ich braku używa oryginału pod dotychczasowym adresem. Zachowuje podpis i tekst alternatywny.

Formaku przetwarza nowe publiczne obrazy w obsługiwanych formatach. Dla istniejących obrazów uruchom php artisan formaku:media-variants w aplikacji Laravel. Jeśli starter działa w Docker Compose, użyj poniższego polecenia.

docker compose --env-file .env.docker exec web php artisan formaku:media-variants

Wydanie Docker zawiera GD z obsługą WebP i EXIF. Na własnym hoście Laravel włącz GD z obsługą WebP oraz EXIF do obsługi JPEG. Jeśli wariant jest niedostępny, Formaku udostępnia oryginał.

Powiąż wersje językowe stron

  1. Zapisz każdą wersję językową jako osobną stronę w tej samej publicznej kolekcji treści.
  2. Na każdej stronie otwórz Wersje językowe. Wpisz Język strony, np. pl lub en-GB, i ten sam Klucz grupy tłumaczeń, np. o-nas. Wybierz Zapisz powiązanie.
  3. Opublikuj każdą stronę. Gdy co najmniej dwie wersje będą publiczne, czytelnicy będą mogli zmienić język. Formaku doda wzajemne odnośniki hreflang z publicznym adresem bazowym z APP_URL.

Potrzebujesz uprawnień do zapisu rekordu i publikowania. Zmiana powiązania działa od razu na opublikowanych stronach. Aby odłączyć stronę, wyczyść oba pola i zapisz powiązanie.

Skonfiguruj SEO i mapę witryny

W panelu otwórz Buduj, wybierz Edytuj model przy publicznej kolekcji treści i w sekcji Metadane SEO przypisz pola tekstowe, które nie są prywatne, do opcjonalnego tytułu i opisu. Zapisz konfigurację kolekcji, uzupełnij pola w rekordzie i opublikuj rewizję strony. Podczas edycji szkicu witryna nadal korzysta z metadanych opublikowanej rewizji.

Gdy tytuł SEO jest pusty, Formaku używa tytułu strony. Gdy opis SEO jest pusty, pomija znacznik opisu.

Starter udostępnia /sitemap.xml ze stroną główną i opublikowanymi stronami z publicznych kolekcji treści. Szkice są pomijane. Ustaw APP_URL na publiczny adres aplikacji, łącznie z podkatalogiem, jeśli go używasz. Przy większej liczbie stron mapa zwraca indeks plików.

Ustaw FORMAKU_SITEMAP=false, jeśli aplikacja udostępnia własną mapę. Jeśli integrujesz samą paczkę CMS, włącz public_routes i sitemap w pliku config/formaku.php, aby skorzystać z mapy Formaku.

Zachowaj prywatność pól wewnętrznych

Od alpha.33 publiczne strony, katalog i karty respektują opcję Prywatne w modelu. Prywatne bloki pozostają w zapisanym szkicu i podglądzie w panelu. Gdy tytuł jest prywatny, Formaku wyświetla publiczną nazwę lub fragment adresu. Widoczność samych plików ustawiasz osobno w bibliotece mediów.

W Buduj → Edytuj model odznacz Prywatne przy slug, jeśli adresy mogą być publiczne. Jeśli mają pozostać prywatne, wyłącz Publiczna kolekcja treści. Aktualizacja ukrywa istniejące kolekcje z prywatnym polem slug i zachowuje ich rekordy oraz rewizje.

Wybieraj role w edytorze modelu

W Buduj → Edytuj model skonfiguruj dostęp do kolekcji i dodaj role z katalogu aplikacji lub wpisz klucz roli. Nowa reguła zaczyna od braku dostępu. Przed zapisaniem wybierz zakres rekordów i prawo edycji. Pusta lista reguł ogranicza dostęp do osób z uprawnieniem Buduj. Aby wrócić do ustawień domyślnych, wybierz Przywróć domyślny dostęp i zapisz model.

Role z katalogu można też wybierać przy uprawnieniach pól. Role przypisuje aplikacja Laravel. Zobacz konfigurację katalogu ról.

Ustaw uprawnienia pól według ról

Otwórz Buduj → Edytuj model → Uprawnienia pól. Zaznacz Ogranicz odczyt lub Ogranicz zapis i wybierz role z katalogu albo wpisz klucze po przecinku. Pusta lista przy włączonym ograniczeniu zostawia dostęp osobom z uprawnieniem Buduj.

Odczyt można ograniczyć dla pól prywatnych innych niż slug. Edytor i historia pomijają niedostępne wartości. Gdy model ukrywa tytuł lub nazwę przed daną rolą, wyszukiwanie po tytule jest dla niej niedostępne. Zapis i przywracanie szkicu zachowują bieżące wartości pól, których użytkownik nie może edytować.

Szablony wymagają prawa zapisu bloków. Kolekcje z regułami pól są niedostępne dla sparowanego asystenta. Lista użycia pliku pomija kolekcje z polami odnośników do mediów, których użytkownik nie może odczytać. Zobacz konfigurację i warunki powrotu do starszej wersji dla aplikacji Laravel.

Zachowaj działające linki po zmianie adresu strony

Zmień końcówkę adresu opublikowanej strony w publicznej kolekcji i opublikuj nową rewizję. Poprzedni adres przekieruje kodem 301 bezpośrednio na bieżący adres, także po kolejnych zmianach. Jeśli inna strona zostanie opublikowana pod dawnym adresem, jej aktualna publikacja ma pierwszeństwo. Ukrycie kolekcji wyłącza również przekierowania do jej stron.

Formaku rejestruje zmiany adresów wykonane po zainstalowaniu wersji alpha.4 lub nowszej. Przed aktualizacją istniejącej instalacji postępuj zgodnie z instrukcją kopii zapasowej i migracji.

Skonfiguruj portal klienta

W starterze włącz rejestrację, jeśli klienci mają sami zakładać konta. Skonfiguruj pocztę i weryfikację adresu przed udostępnieniem rejestracji lub resetu hasła. Klient składa i przegląda własne zgłoszenia pod adresem /portal. Pracownik może przypisać zgłoszenie członkowi zespołu przy zmianie statusu.

Na wąskich ekranach katalog publiczny i portal klienta pokazują odnośniki do poprzedniej i następnej strony. Na szerszych ekranach widać numery stron i liczbę wyników.

W historii zgłoszeń wybierz stan i kliknij Filtruj. Aktywne filtry obowiązują także na kolejnych stronach. Kliknij Wyczyść filtry, aby wrócić do pełnej listy własnych zgłoszeń.

Wpisz dokładny Numer zgłoszenia, aby znaleźć własne zgłoszenie. Filtry numeru i stanu działają razem. Temat pojawia się przy wyniku, jeśli masz do niego dostęp.

Dodaj pola do formularza zgłoszeń

W Buduj → Edytuj model otwórz kolekcję danych requests i zaznacz pola w sekcji Pola portalu klienta. Formularz zawsze zawiera temat i opis. Możesz dodać tekst, liczby, daty, pola tak/nie i listy wyboru. Zapisz model, aby zaktualizować /portal.

W sekcji Kolejność pól w formularzu kliknij Przesuń w górę lub Przesuń w dół przy wybranym polu, a następnie zapisz model. Temat i opis są na początku. Formularz i szczegóły zgłoszenia pokazują dodatkowe pola w zapisanej kolejności, zgodnie z uprawnieniami klienta.

Dodatkowe pola uwzględniają ustawienie Wymagane i uprawnienia klienta. W szczegółach własnego zgłoszenia klient widzi zapisane wartości, które może odczytać. Pola wewnętrzne oznacz jako prywatne.

Włącz załączniki do zgłoszeń

W modelu requests włącz Załączniki do zgłoszeń. Ustaw limit od jednego do trzech plików, maksymalny rozmiar od 1 do 5 MiB na plik i wybierz co najmniej jeden typ spośród PDF, PNG i JPEG. Zapisz model. Portal pokazuje wybrane limity i stosuje je przy wysłaniu zgłoszenia. Domyślnie dostępne są wszystkie trzy typy, do trzech plików i do 5 MiB na plik.

Właściciel i pracownicy z dostępem do zgłoszenia mogą pobrać pliki w jego szczegółach. Zmiana limitów dotyczy nowych plików.

Wyłącz Załączniki do zgłoszeń, aby wstrzymać dodawanie nowych plików. Zapisane pliki pozostają dostępne zgodnie z uprawnieniami do zgłoszenia. W aplikacji Laravel sprawdź konfigurację prywatnego dysku i limitów przesyłania.

Ustaw zakres dostępu redaktora i publikującego do wszystkich, własnych lub przypisanych rekordów albo odbierz dostęp. Prawo zapisu skonfiguruj osobno. Po włączeniu reguł kolekcji role bez wpisu tracą dostęp. Oznacz pola wewnętrzne jako prywatne, aby nie trafiały do odpowiedzi portalu.

Połącz z aplikacją Laravel

W istniejącej aplikacji Laravel 13 z PHP 8.4 lub nowszym dodaj repozytorium Composer Formaku i zainstaluj wydanie. Pakiet zawiera zbudowany panel.

composer config repositories.formaku composer https://formaku.eu/composer
composer require 'formaku/cms:0.1.0-alpha.72' --prefer-dist
php artisan formaku:install
php artisan migrate

Ustaw mechanizm sesji i funkcję autoryzacji aplikacji w config/formaku.php. Zaloguj się w aplikacji Laravel na konto z uprawnieniem work, a następnie otwórz /formaku.

Dostęp do panelu jest domyślnie zablokowany, a trasy publiczne wymagają włączenia. Pakiet używa uwierzytelniania aplikacji gospodarza. Jeśli potrzebujesz gotowego logowania i portalu, użyj startera.

Skorzystaj z przykładów rozszerzeń, aby zarejestrować własny blok oraz wywołać zasób i akcję przez uwierzytelnione trasy w aplikacji Laravel.

Sprawdź instalację

Uruchom php artisan formaku:doctor w katalogu aplikacji Laravel. Polecenie sprawdza migracje Formaku, konfigurację dostępu do panelu i opublikowane pliki JavaScript oraz CSS w trybie odczytu. Jeśli wykryje problem, skorzystaj z poradnika dewelopera.

Zainstaluj pakiet z pliku ZIP

Pobierz pakiet Composer w ZIP (v0.1.0-alpha.72) i sumę kontrolną SHA-256. Sprawdź sumę przed instalacją. Skorzystaj z instrukcji instalacji z ZIP-u, aby zarejestrować pakiet w Composerze.

Przed publikacją nowego wydania GitHub Actions instaluje jego ZIP w osobnej aplikacji Laravel 13 z SQLite. Test sprawdza migracje Formaku i publikację plików panelu oraz potwierdza, że aplikacja zachowuje własną trasę i rekord testowy.

Zbuduj arkusz stylów CMS

Arkusz Formaku powstaje ze źródeł panelu, widoków Blade i kodu renderowania. Uruchom npm run build w głównym katalogu repozytorium. Jeśli rozszerzenie Laravel potrzebuje dodatkowych klas, skompiluj jego style w aplikacji gospodarza. Zobacz poradnik dewelopera.

Zaktualizuj istniejącą instalację Composer

Po aktualizacji do wydania v0.1.0-alpha.72 uruchom te polecenia w aplikacji Laravel przed przywróceniem ruchu.

php artisan formaku:install
php artisan migrate --force

Alpha.61 dodaje indeks historii rewizji dla PostgreSQL i SQLite. Wykonaj migrację przed wznowieniem ruchu. Podczas budowy indeksu PostgreSQL blokuje zapisy do tabeli rewizji. Istniejące szkice, publikacje i rewizje pozostają w bazie.

Przed przywróceniem ruchu uruchom php artisan formaku:doctor, aby sprawdzić migracje, konfigurację dostępu do panelu i opublikowane pliki CSS oraz JavaScript.

Od alpha.31 formaku:install usuwa skompilowane kopie szablonów Blade pakietu. Widoki aplikacji gospodarza pozostają w cache. Jeśli wdrożenie kompiluje widoki z wyprzedzeniem, wykonaj następnie php artisan view:cache. Przy instalacji alpha.30 po aktualizacji wykonaj php artisan view:clear.

Zarejestruj własne typy pól i bloków

W providerze Laravel zarejestruj typ pola metodą Registry::field(). Otwórz Buduj → Edytuj model i wybierz etykietę rozszerzenia na liście typów. W formularzu rekordu możesz edytować tekst, tekst formatowany, liczby, daty, wartości Tak/Nie i opcje listy. Pola, których typ nie ma obsługiwanej kontrolki, są widoczne tylko do odczytu. Na przykład pole ceny może przyjmować całkowitą liczbę groszy i odrzucać wartości ujemne.

Zarejestruj PanelBlockType metodą Registry::block(). W edytorze strony wybierz jego etykietę w sekcji Sekcje strony i dodaj blok. Edytor pokazuje ustawienia tekstowe, wielowierszowe, liczbowe, Tak/Nie i listy wyboru zdefiniowane w panelSchema(). Jeśli blok przyjmuje dzieci, dodaj lub przenieś do niego inne bloki, a potem zapisz i otwórz podgląd szkicu.

Ustawienia bez obsługiwanej kontrolki i ustawienia starszych bloków bez metadanych pozostają w szkicu. Do ich edycji użyj API lub edytora w aplikacji Laravel. Zobacz przykład ustawień bloku i przykład typu pola.

Pokaż zasoby i akcje Laravel w panelu

Zarejestruj zasób lub akcję w aplikacji Laravel z jawną konfiguracją panelu. Określ uprawnienia do rozszerzenia oraz wybierz kolumny tabeli lub pola formularza. Uprawnieni użytkownicy znajdą je w sekcji Rozszerzenia.

Przykładowy provider pokazuje profil zalogowanego użytkownika i wyświetla podgląd komunikatu. Skorzystaj z instrukcji konfiguracji, aby wypróbować go w aplikacji Laravel.

Sprawdź propozycję strony przygotowaną przez AI

Opcjonalne AI skonfigurujesz na serwerze przez OPENAI_API_KEY / OPENAI_MODEL lub GEMINI_API_KEY / GEMINI_MODEL. Uruchom proces kolejki, wygeneruj propozycję strony i odśwież listę zadań.

Aby ograniczyć liczbę tokenów wyjściowych dla pojedynczego żądania, ustaw na serwerze OPENAI_MAX_OUTPUT_TOKENS lub GEMINI_MAX_OUTPUT_TOKENS. Domyślnie każdy dostawca ma limit 3000. Wpisz liczbę całkowitą od 16 do 3000. Po zmianie odśwież cache konfiguracji, jeśli go używasz, i zrestartuj procesy kolejki.

Formaku sprawdza uporządkowaną listę sekcji przed oznaczeniem propozycji jako gotowej. Jeśli generowanie się nie powiedzie, przeczytaj komunikat na karcie zadania przed wysłaniem nowego żądania.

Przy gotowym zadaniu kliknij Sprawdź propozycję i wybierz kolekcję, w której możesz tworzyć strony oraz edytować tytuł i sekcje. Sprawdź tytuł, proponowany adres URL, jeśli kolekcja go obsługuje, oraz treść i kolejność sekcji. Zastosuj jako nowy szkic otworzy edytor z tymi wartościami. Kliknij Zapisz szkic, aby utworzyć rekord. Publikację uruchom osobno z edytora.

Podgląd wymienia wymagane pola dostępne do edycji, które pozostaną puste po zastosowaniu propozycji. Lista zmienia się wraz z wyborem kolekcji. Uzupełnij wskazane pola w edytorze przed zapisaniem szkicu.

Sparuj asystenta witryny

Sparuj Codexa, aby tworzyć i edytować szkice stron w jednej wybranej publicznej kolekcji treści. Kolekcja musi być wolna od pól prywatnych i relacji.

  1. Otwórz Asystent witryny w panelu administracyjnym i wybierz kolekcję.
  2. Pobierz adapter MCP i wygeneruj kod parowania. Mając Node.js 20 lub nowszy, uruchom polecenie pokazane w panelu z katalogu pobranego adaptera i wpisz kod w terminalu.
  3. Uruchom ponownie Codexa i poproś go o utworzenie lub edycję szkicu w wybranej kolekcji.

Kod jest jednorazowy i wygasa po pięciu minutach. Połączenie trwa 30 dni. Parowanie domyślnie daje dostęp do szkiców. Włącz prawo publikacji osobno podczas parowania, jeśli chcesz zlecać asystentowi publikację. Aby zakończyć połączenie, wybierz Cofnij dostęp w panelu.

Sparuj innego klienta MCP

Od alpha.17 w kliencie MCP obsługującym stdio dopisz --print-config do polecenia parowania z panelu. Po wpisaniu jednorazowego kodu wklej wygenerowany wpis JSON mcpServers do konfiguracji klienta. Jeśli klient używa innego formatu, skopiuj wartości command i args. Uruchom ponownie klienta. Token pozostaje w lokalnym pliku połączenia.

Zaktualizuj sparowany adapter

Od wersji CMS alpha.20 pobierz aktualny adapter z panelu. Jeśli połączenie jest nadal aktywne, uruchom poniższe polecenie z katalogu pobranego pliku. Podaj ten sam pełny adres, który panel wyświetla w poleceniu parowania.

node formaku-assistant.mjs update ADRES_Z_PANELU

Uruchom ponownie klienta MCP, aby wczytać nowe narzędzia. Aktualizacja podmienia lokalny adapter i zachowuje dotychczasowy token oraz konfigurację klienta. Wróć do instrukcji parowania, jeśli połączenie wygasło, zostało cofnięte lub ma działać pod innym adresem.

Sprawdź szkic i otwórz podgląd

Od alpha.17 możesz użyć aktualnego adaptera MCP, aby poprosić Codexa o sprawdzenie pól kolekcji i walidację szkicu z wbudowanych bloków przed zapisem. Walidacja nie zapisuje szkicu. Po zapisaniu poproś o link do podglądu i otwórz go w przeglądarce z aktywną sesją Formaku na koncie z dostępem do szkicu.

Codex może użyć bloków z zapisanego szablonu w sparowanej kolekcji.

Porównaj zapisany szkic z publikacją

Zaktualizuj adapter MCP i poproś sparowanego asystenta o porównanie zapisanego szkicu strony z jej aktualną opublikowaną rewizją. Asystent poda zmienione pola i wersję rekordu. Jeśli strona czeka na pierwszą publikację, pokaże wartości ze szkicu.

Jeśli połączenie ma prawo publikacji, możesz zlecić asystentowi opublikowanie przejrzanej wersji. Jeśli ktoś w międzyczasie zmieni szkic, przejrzyj zmiany ponownie, zanim zlecisz publikację.

Użyj opublikowanego obrazu w szkicu

Od alpha.18 poproś asystenta o wyświetlenie listy publicznych obrazów użytych w aktualnie opublikowanych wersjach stron sparowanej kolekcji. Asystent może wstawić identyfikator wybranego obrazu do bloku obrazu w szkicu. Lista pomija pliki prywatne oraz obrazy użyte wyłącznie w szkicach, starszych rewizjach lub innych kolekcjach.

Podczas walidacji i zapisu szkicu asystent sprawdza też zagnieżdżone listy bloków. Jeśli lista przekracza 100 bloków lub zagnieżdżenie przekracza limit 10 poziomów, skróć lub uprość układ przed ponownym zapisem.

Odczytaj warianty produktów z Commerce

Od wersji CMS alpha.19 możesz poprosić sparowanego asystenta o listę produktów do szkicu. Asystent korzysta z publicznego katalogu Commerce v2, jeśli instalacja go udostępnia. Każda pozycja ma osobny identyfikator produktu i wariantu. Wariant może mieć własną etykietę, np. rozmiar, a pozycja zawiera jego cenę i informację o dostępności.

Jeśli instalacja udostępnia tylko katalog v1, asystent nadal odczytuje z niego produkty. Odczyt obu wersji publicznego katalogu odbywa się bez wysyłania tokenu CMS.

Od wersji CMS alpha.20, jeśli publiczny katalog Commerce v2 udostępnia kategorie, poproś asystenta o listę opublikowanych kategorii i zawężenie wariantów według slugu kategorii. Na przykład w szkicu oferty możesz użyć wyłącznie wariantów z kategorii kawa.

Od wersji CMS alpha.21, jeśli kompatybilny sklep Commerce zwraca publiczną ścieżkę karty produktu w polu public_path, poproś asystenta o użycie jej w przycisku produktu w szkicu. Adapter przyjmuje tylko ścieżki w obrębie tej samej witryny. Jeśli katalog nie podaje ścieżki, której można użyć, zachowaj dotychczasowy link do katalogu.

Przygotuj wdrożenie CMS

Aby zbudować obraz z panelu, otwórz Wydania i podaj pełny SHA commita z gałęzi main. Kliknij Odśwież stan w wierszu wydania, żeby odczytać stan budowy z GitHub Actions. Po udanej budowie otwórz przebieg i skopiuj digest obrazu z podsumowania. Wdrożenie odbywa się w osobnym workflow.

Sprawdź wynik próby wdrożenia

W Wydania → Potwierdzenie wdrożenia podaj liczbowy identyfikator uruchomienia GitHub Actions, UUID wdrożenia i pełny adres obrazu wraz z digestem. Kliknij Sprawdź potwierdzenie, aby odczytać raport ostatniej próby workflow Deploy existing image na gałęzi main.

Raport pokazuje kod wyjścia SSH oraz stan zgłoszony przez host po tej próbie, w tym wynik przywracania poprzedniej wersji, jeśli jest dostępny. Gdy raport lub stan hosta jest niedostępny, otwórz podsumowanie workflow i odczytaj bieżący stan poleceniem kontrolera. Host CMS wymaga rozszerzenia ZIP dla PHP i tokenu GitHub z uprawnieniem odczytu Actions.

Odczytaj ostatni zapis kontrolera

Uruchom Read deployment status na gałęzi main i podaj UUID wdrożenia oraz pełny adres obrazu wraz z digestem. Workflow odczytuje stan kontrolera bez uruchamiania wdrożenia. Podsumowanie pokazuje ostatni stan zapisany dla tej próby. Jeśli nowsza próba zastąpiła wpis, workflow zgłosi brak dostępnego stanu.

Zmierz wydajność Formaku

Benchmark referencyjny mierzy publiczną stronę i uwierzytelnioną listę rekordów na danych syntetycznych. Korzysta z natywnego Dockera na Linux AMD64 i osobnych limitów usług o łącznej wartości 2 vCPU i 4 GiB. Czterej klienci mierzą każdy endpoint osobno po rozgrzewce. Raport zawiera liczbę żądań i błędów, przepustowość oraz czasy odpowiedzi p50, p95 i p99.

Aby powtórzyć pomiary, użyj digestu opublikowanego obrazu i wykonaj kroki benchmarku.

W trzech próbach alpha.65 wykonano 7976 żądań bez błędów. P95 mieściło się w zakresie 94,6–97,3 ms dla strony publicznej i 122,0–144,4 ms dla uwierzytelnionej listy rekordów. Zobacz podsumowanie przebiegu i raporty JSON.

Skonfiguruj PostgreSQL 17 lub MySQL 8.4, ustaw stały APP_KEY i hasło bazy. Uruchom proces WWW, kolejkę i harmonogram. Starter Docker Compose wykorzystuje ten sam obraz dla wszystkich trzech procesów.

Skonfiguruj reverse proxy z HTTPS, sprawdź kopie zapasowe i odtwarzanie, a przed udostępnieniem aplikacji przetestuj portal oraz publikację.

Przed aktualizacją istniejącej instalacji wykonaj kopię bazy danych i przesłanych plików. Przed uruchomieniem usług po aktualizacji wykonaj php artisan migrate --force w nowej wersji. Alpha.49 nie wymaga nowej migracji. Alpha.37 dodaje tabelę załączników do zgłoszeń. Wykonaj kopię bazy razem z prywatnymi plikami. Alpha.30 dodaje tabelę powiązań wersji językowych i zachowuje istniejące szkice oraz opublikowane strony. Alpha.15 dodała tabelę szablonów stron dla kolekcji. Przy aktualizacji z alpha.12 lub starszej wersji to samo polecenie zastosuje migrację ustawień menu i stopki z alpha.13. Przy aktualizacji z alpha.10 lub starszej wersji migracja alpha.11 tworzy indeks użycia plików i wypełnia go na podstawie bieżących szkiców i opublikowanych wersji. Polecenie wykona też zaległe migracje, w tym dodanie tabeli przekierowań z alpha.4 oraz, przy aktualizacji z pierwszej alfy, tabel do parowania asystenta.

Przy instalacji przez Composer wykonaj kroki aktualizacji aplikacji Laravel przed przywróceniem ruchu.

Instrukcja Docker Compose pokazuje, jak zbudować obraz ze źródeł oznaczonych tagiem. Możesz też pobrać publiczny obraz Linux AMD64 według digestu. Compose osobno sprawdza stan procesu kolejki i harmonogramu.

docker pull ghcr.io/formaku/formaku@sha256:a083faacb3e25632c2e5f72ae45c85b0e65c294e81674e26dd98d42f2feeaece

Sprawdź źródło i rewizję obrazu

Od alpha.39 workflow wydania sprawdza trzy etykiety OCI publicznego obrazu Linux AMD64 pobranego według digestu. org.opencontainers.image.source wskazuje repozytorium Formaku, org.opencontainers.image.revision podaje pełny SHA commita, a org.opencontainers.image.version podaje wersję wydania lub SHA źródła w kompilacji ręcznej. Instrukcja wdrożenia pokazuje, jak odczytać etykiety w Dockerze.

Przetestuj opublikowany obraz

Otwórz CI → Run workflow na GitHubie i wklej digest z wydania. Test pobiera wskazany obraz, sprawdza instalację i uruchamia usługi Compose na świeżej bazie. Użyj wersji alpha.48 lub nowszej. Zobacz instrukcję GitHub Actions.

Sprawdź stan wdrożenia i powrotu do poprzedniego obrazu

Na hoście z kontrolerem Formaku uruchom sudo /usr/local/sbin/formaku-deployctl status. Przy awarii status wskazuje, czy Compose uruchomił poprzedni obraz, czy jego stan nie został potwierdzony, czy zabrakło poprzedniego obrazu lub czy błąd wystąpił przed zatrzymaniem usług. Pole backup wskazuje ukończone zaszyfrowane archiwum. Kolejną próbę uruchom z nowym UUID wydania.

Powrót do poprzedniego obrazu korzysta z istniejącej bazy i plików. Znaczenie statusów i zasady odzyskiwania danych opisuje instrukcja wdrożenia.

Odczytaj wynik wdrożenia w GitHub Actions

Po przebiegu wdrożenia w alpha.41 otwórz jego podsumowanie. Znajdziesz tam stan dla podanego wydania i obrazu. Po awarii może się tam pojawić wynik powrotu do poprzedniego obrazu i UUID ukończonej kopii. Workflow zachowuje pierwotny wynik polecenia wdrożenia.

Aby włączyć odczyt statusu, zaktualizuj kontroler i wymuszone polecenie SSH oraz dodaj regułę odczytu zgodnie z instrukcją konfiguracji hosta.

Instrukcje dotyczą wydania wstępnego Formaku v0.1.0-alpha.72. Zmiany w kodzie i zgłoszenia możesz śledzić w repozytorium CMS.

Formaku Commerce

Commerce to opcjonalny pakiet API dla Formaku i innych aplikacji Laravel. Wersja developerska obsługuje jeden sklep w jednej walucie, katalog SKU, zamówienia z konta klienta, odbiór osobisty i ręczne potwierdzanie przelewu. Do odbioru użyj środowiska testowego i danych syntetycznych.

Instalacja w aplikacji Laravel

Potrzebujesz PHP 8.4+, Laravel 13.17 lub nowszego z linii 13.x oraz kopii kodu paczki. Uruchom polecenia w katalogu aplikacji gospodarza. Podmień przykładową ścieżkę na lokalny katalog paczki. Instalacja z Packagist jest przewidziana po wydaniu.

composer config repositories.formaku-commerce path "/absolute/path/to/packages/commerce"
composer require formaku/commerce:@dev
php artisan vendor:publish --tag=formaku-commerce-config
php artisan migrate
  1. W config/formaku-commerce.php wybierz walutę przed utworzeniem produktów i wskaż guard, jeśli aplikacja używa innego niż domyślny. Kwoty podawaj w najmniejszych jednostkach waluty, np. 4990 oznacza 49,90 PLN.
  2. Zdefiniuj w aplikacji reguły Laravel Gate formaku-commerce.catalog, formaku-commerce.stock, formaku-commerce.orders i formaku-commerce.payments. Przydziel uprawnienie do potwierdzania wpłat osobno.
  3. Ustaw FORMAKU_COMMERCE_ENABLED=true. Jeśli aplikacja używa cache konfiguracji i tras, przebuduj go. Uruchom harmonogram Laravel, który co minutę wywołuje formaku:commerce-expire.

Przetestuj przebieg zamówienia

Domyślny prefiks API to /formaku/api/v1/commerce. Wyślij Accept: application/json. Katalog jest publiczny. Pozostałe trasy używają sesji Laravel, a żądania modyfikujące dane wymagają ochrony CSRF.

  1. Utwórz opublikowany produkt przez POST /admin/products. Przekaż sku, name, price_minor, available oraz published: true. Sprawdź, czy pojawił się w GET /products.
  2. Zaloguj się jako klient. Wyślij POST /quotes z listą items zawierającą product_id i quantity. W POST /orders podaj identyfikator wyceny jako quote_id. Klient sprawdza własne zamówienie przez GET /orders/{id}.
  3. Jako osoba uprawniona wyślij POST /admin/orders/{id}/pay z reference, amount_minor i currency. Po odbiorze wywołaj POST /admin/orders/{id}/complete.
  4. Na osobnym zamówieniu sprawdź anulowanie przez POST /admin/orders/{id}/cancel i zwolnienie zapasu po upływie rezerwacji.

Wycena jest ważna przez 10 minut. Przy zmianie ceny lub braku zapasu API zwraca 409. Pobierz wtedy nową wycenę. Ponowienie zamówienia z tym samym quote_id zwraca istniejące zamówienie. Rezerwacja domyślnie wygasa po 30 minutach. Spóźniony przelew rozlicz ręcznie.

Do korekty zapasu użyj POST /admin/products/{id}/stock z delta i expected_available. Przy konflikcie odczytaj bieżący stan przed ponowieniem korekty.

Przed użyciem produkcyjnym sprawdź uprawnienia, równoległe zamówienia ostatniej sztuki oraz zwalnianie rezerwacji na docelowej bazie. Gotowy sklep i panel handlowy, warianty, podatki, wysyłka, płatności online i zwroty są poza zakresem tej wersji.