gemvc/stcms

A lightweight, static-like PHP website with clean architecture and multi-language support.

Maintainers

Details

github.com/gemvc/stcms

Source

Issues

Installs: 7

Dependents: 0

Suggesters: 0

Security: 0

Stars: 1

Watchers: 0

Forks: 0

Open Issues: 0

Language:Twig

1.1.3 2025-07-08 14:21 UTC

This package is not auto-updated.

Last update: 2025-07-08 14:25:46 UTC


README

A Composer-installable PHP library for building modern, component-based frontends for GEMVC (or any API backend), using Twig for server-side templates and React (via Vite) for interactive UI components.

Features

  • πŸš€ Hybrid Rendering: Twig for server-side, React for interactive components
  • πŸ”Œ API Integration: Fetch data from GEMVC or any API using Guzzle
  • ⚑ Modern Caching: Symfony Cache (APCu/file)
  • πŸ› οΈ CLI Project Init: Scaffold new projects with vendor/gemvc/stcms/bin/stcms init
  • 🎨 Component-based UI: React components in /assets/js/components/, bundled with Vite
  • πŸ—‚οΈ Multi-language Support: Easily add new languages
  • πŸ”’ Config via .env: Symfony Dotenv for environment config
  • 🧩 Extensible: Easy for both PHP and frontend devs
  • πŸ›‘οΈ Security: Apache security headers and file protection
  • πŸ“¦ Standardized Setup: Consistent project initialization

Quick Start

1. Install via Composer

composer require gemvc/stcms

2. Initialize a New Project

php vendor/gemvc/stcms/bin/stcms init

3. Build Frontend Assets (React via Vite)

npm install
npx vite build

4. Configure Environment

Edit .env for API base URL, cache, etc.

5. Test if CMS successfully installed

php -S localhost:8000

6. Start Developing

  • Pages in /pages/ (real user-facing pages)
  • Templates in /templates/ (layouts, partials, reusable Twig blocks)
  • React components in /assets/js/components/
  • API calls via Guzzle in PHP

Project Structure

/
β”œβ”€β”€ src/                    # PHP library code
β”‚   β”œβ”€β”€ Core/               # Core classes (Application, Router, etc.)
β”‚   β”‚   β”œβ”€β”€ Application.php # Main application orchestrator
β”‚   β”‚   β”œβ”€β”€ Router.php      # URL routing and request handling
β”‚   β”‚   β”œβ”€β”€ Request.php     # HTTP request encapsulation
β”‚   β”‚   β”œβ”€β”€ Response.php    # HTTP response handling
β”‚   β”‚   β”œβ”€β”€ TemplateEngine.php # Twig template rendering
β”‚   β”‚   └── ApiClient.php   # HTTP API communication
β”‚   β”œβ”€β”€ Command/            # CLI commands
β”‚   └── setup/              # Template files for project initialization
β”œβ”€β”€ pages/                  # Real user-facing pages (Twig)
β”œβ”€β”€ templates/              # Twig layouts, partials, and reusable templates
β”œβ”€β”€ assets/
β”‚   β”œβ”€β”€ js/
β”‚   β”‚   β”œβ”€β”€ components/     # React components (JSX)
β”‚   β”‚   └── app.jsx         # Main React entry
β”‚   └── css/                # CSS (optional, Tailwind via CDN or Vite)
β”œβ”€β”€ public/
β”‚   └── assets/js/          # Vite build output
β”œβ”€β”€ .env                    # Config
β”œβ”€β”€ .htaccess               # Apache configuration with security headers
β”œβ”€β”€ index.php               # Main entry point
β”œβ”€β”€ vite.config.js          # Vite config
β”œβ”€β”€ package.json            # Frontend dependencies
β”œβ”€β”€ composer.json           # Composer config
└── bin/stcms               # CLI entry point

Core PHP Classes

Application.php

Main application orchestrator that manages sessions, JWT authentication, and coordinates all components.

Router.php

URL routing with support for exact matches, dynamic routes (/user/{id}), and automatic template rendering.

TemplateEngine.php

Twig integration with custom functions:

  • asset() - Generate asset URLs
  • route() - Generate route URLs
  • json_encode() - JSON encoding helper
  • is_authenticated() - Authentication check

ApiClient.php

HTTP API communication using Guzzle with JWT authentication support.

How It Works

  • Twig renders main pages from /pages/; React components are mounted where needed
  • Reusable layouts/partials in /templates/
  • API data fetched via Guzzle (with Symfony Cache)
  • Frontend devs build React components in /assets/js/components/
  • Vite bundles JS for use in templates/pages
  • Config and cache are environment-driven

Example: Hybrid Rendering

Twig page (in /pages/):

{% extends 'layout.twig' %}
{% block content %}
<div id="user-profile-root" data-user="{{ user|json_encode }}" {% if jwt %}data-jwt="{{ jwt }}"{% endif %}></div>
{% endblock %}
<script src="{{ asset('js/app.js') }}"></script>

React entry (app.jsx):

import React from 'react';
import { createRoot } from 'react-dom/client';
import UserProfile from './components/UserProfile';

const el = document.getElementById('user-profile-root');
if (el) {
  const user = JSON.parse(el.dataset.user);
  const jwt = el.dataset.jwt; // Only present if authenticated
  createRoot(el).render(<UserProfile user={user} jwt={jwt} />);
}

Authentication Flow & Security

  • JWT is only exposed to React if the user is authenticated (JWT is present in PHP session).
  • If not authenticated, no JWT is exposedβ€”React knows to show login or restrict access.
  • React components use the JWT for API requests (e.g., via Axios/fetch, in Authorization header).
  • JWT is never generated or verified in the frontendβ€”all JWT logic is handled by the backend (GEMVC API).
  • Session management and login/logout handled by PHP backend.
  • Best practice: Always validate JWTs on the backend for every API request.

Setup Folder Structure

The src/setup/ folder contains all template files that get copied during project initialization:

src/setup/
β”œβ”€β”€ .gitignore           # Git ignore patterns
β”œβ”€β”€ .htaccess           # Apache configuration with security headers
β”œβ”€β”€ index.php           # Main entry point
β”œβ”€β”€ env.template        # Environment configuration template
β”œβ”€β”€ vite.config.js      # Vite build configuration
β”œβ”€β”€ package.json        # Frontend dependencies
β”œβ”€β”€ templates/          # Layouts, partials, reusable Twig blocks
β”‚   └── example.twig    # Example template
β”œβ”€β”€ pages/              # Real user-facing pages (Twig)
β”‚   └── index.twig      # Example landing page
└── assets/js/
    β”œβ”€β”€ app.jsx         # React entry point
    └── components/
        └── UserProfile.jsx # Example React component

Benefits

  • βœ… Clean separation of backend, pages, templates, and frontend components
  • βœ… Easy for both PHP and React developers
  • βœ… Fast, SEO-friendly, and interactive
  • βœ… Works on most hosting (APCu/file cache)
  • βœ… Extensible and maintainable
  • βœ… Standardized project initialization
  • βœ… Security headers and file protection
  • βœ… Modern development workflow

For PHP Developers

  • Use /pages/ for real pages, /templates/ for layouts/partials
  • Fetch API data with Guzzle (and cache it)
  • Pass data to React components via JSON in the DOM
  • Expose JWT to React only if authenticated
  • Use the Router for custom route handling

For React Developers

  • Build components in /assets/js/components/
  • Use Vite for fast dev/build
  • Mount components anywhere in Twig pages/templates
  • Use JWT (if present) for authenticated API requests
  • Leverage the asset() function for static file URLs

CLI Commands

Initialize Project

vendor/bin/stcms init

Creates a new project with all necessary files and folder structure.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Test thoroughly
  5. Submit a pull request

License

MIT

Support

  • Documentation: /en/docs
  • Issues: GitHub Issues
  • Discussions: GitHub Discussions

Changelog

Version 1.0.0

  • Initial release with complete PHP framework
  • Core classes: Application, Router, Request, Response, TemplateEngine, ApiClient
  • CLI project initialization
  • Hybrid Twig/React rendering
  • Security headers and file protection
  • Standardized setup folder structure
  • Beautiful landing page template
  • Comprehensive .gitignore patterns

STCMS - Making hybrid PHP/React development simple and powerful! πŸš€