Tagixo Docs
Back to Website Start Here

Getting Started

Installation and Prerequisites

Install package dependencies and verify your baseline Laravel setup before wiring the builder.

8 min read Route: /documentation/core/installation-and-prerequisites

Installation and Prerequisites

Tagixo is a visual page and form builder for Laravel. The core package (ccast/tagixo) ships the builder engine, rendering pipeline, REST bootstrap/save endpoints, and a pre-built Vue 3 + PrimeVue frontend bundle. This page covers everything you need before writing a single line of integration code.

If you are using an admin panel SDK, refer to the Filament or Primix SDK documentation sections.

System requirements

Dependency Minimum Notes
PHP 8.2 PHP 8.3 recommended
Laravel 10 Tested on 10, 11, 12, 13
MySQL 8.0+ —
MariaDB 10.4+ —
PostgreSQL 14+ Recommended for production
SQLite 3.35+ Fine for local dev and CI
Redis optional Required only if you use the redis cache or session driver
Node / npm not required The builder bundle is pre-compiled and published as static files

No npm step in your app. The Vue 3 + PrimeVue + Tiptap bundle is compiled inside the package and delivered as static files under public/vendor/tagixo/. You publish those files once with vendor:publish and re-publish after every upgrade. Your own Vite pipeline is unaffected.

Required PHP extensions

All of these are enabled by default in official PHP Docker images, Laravel Herd, and Valet:

  • ext-json
  • ext-fileinfo — media upload MIME detection
  • ext-gd or ext-imagick — thumbnail generation
  • ext-mbstring
  • ext-pdo

Octane / Swoole compatibility

Tagixo is compatible with Laravel Octane (Swoole and FrankenPHP). The package holds no static state that leaks between requests. Keep two points in mind:

  • After editing config/tagixo.php, run php artisan octane:reload (or optimize:clear and restart the worker). Octane holds the bootstrapped app in memory and does not re-read config files automatically.
  • Preview signed URLs are stateless — no server-side session is required. The signed URL carries the full payload.

If you are running PHP-FPM or the built-in development server, none of this applies.

Composer setup for the private VCS package

ccast/tagixo is hosted on a private GitHub repository. You need a GitHub Personal Access Token (PAT) with Contents: Read permission on the c-cast/tagixo repository before Composer can clone it.

Declare the VCS source

Add the repository entry to your project's composer.json before installing:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/c-cast/tagixo.git"
        }
    ]
}

Without this entry Composer has no way to locate ccast/tagixo and the install fails with a package not found error.

Authenticate with your PAT

Local development — global auth.json:

composer config --global --auth github-oauth.github.com <YOUR_PAT>

Writes to ~/.composer/auth.json. Available to every project on the machine.

CI / Docker — environment variable:

export COMPOSER_AUTH='{"github-oauth":{"github.com":"<YOUR_PAT>"}}'
composer install

Pass it as a BuildKit secret in Docker to keep the token out of the image layers:

RUN --mount=type=secret,id=composer_auth \
    COMPOSER_AUTH=$(cat /run/secrets/composer_auth) \
    composer install --no-dev --optimize-autoloader

Team project — project-level auth.json:

Create auth.json at the project root and add it to .gitignore immediately. Never commit it.

{
    "github-oauth": {
        "github.com": "<YOUR_PAT>"
    }
}

Install the core package

composer require ccast/tagixo:"^1.0"

Pin a version range in production projects. Omitting a constraint installs the latest release, which may include breaking changes on the next composer update.

Service provider auto-discovery

The package registers Ccast\Tagixo\TagixoServiceProvider via Laravel's package discovery mechanism — declared in composer.json's extra.laravel.providers array. You do not need to touch config/app.php.

Confirm discovery ran cleanly after install:

php artisan package:discover --ansi
# Expected output includes:
# Discovered Package: ccast/tagixo

Publish and run migrations

php artisan vendor:publish --tag=tagixo-migrations
php artisan migrate

The following tables are created:

Table Purpose
tgx_pages Page records — slug, title, published state, builder payload
tgx_layouts Layout templates wrapping page content
tgx_menus Named navigation menus
tgx_menu_items Flat/nested menu entries with link targets
tgx_forms Form schema definitions
tgx_global_variables Site-wide design tokens (colors, fonts, spacing)
tgx_media Media library entries
tgx_mail_templates Transactional email templates
tgx_pdf_templates PDF generation templates

Existing migrations. The published migration files land in database/migrations/. Inspect them before running migrate on an existing database — column definitions are additive and do not touch unrelated tables, but reviewing them before deploying to production is good practice.

Publish the configuration file

php artisan vendor:publish --tag=tagixo-config

This writes config/tagixo.php. The file is self-documented with inline comments. The most relevant top-level keys for initial setup:

Key Default Description
enable_default_types false Auto-registers DefaultPageType/MailType/PdfType; set to true by tagixo:install
route_middleware ['web','auth'] Middleware for all builder API routes
public_route_middleware ['web'] Middleware for public-facing routes (form submissions)
frontend.auto_routes false Registers catch-all /{slug} route for published pages
frontend.model Page::class Page model class resolved by the frontend controller
media_gallery.disk 'public' Laravel storage disk for media uploads
preview.url_ttl_seconds 300 Signed preview URL lifetime in seconds
scaffolding.path 'app/tagixo' Directory where make:tagixo-* generates classes
scaffolding.namespace null (auto-derived) PHP namespace; derived from path if not set
cache.enabled / cache.ttl true / 3600 Component config caching

After editing config/tagixo.php, always clear the config cache:

php artisan optimize:clear
# or on Octane:
php artisan octane:reload

Scaffolding path

scaffolding.path and scaffolding.namespace tell the make:tagixo-* generators where to write new classes. If your project follows a non-standard structure, set these before scaffolding:

// config/tagixo.php
'scaffolding' => [
    'path'      => 'app/Http/Builder',
    'namespace' => 'App\\Http\\Builder', // null = auto-derived from path
],

Publish static assets

php artisan vendor:publish --tag=tagixo-assets

Files written to public/vendor/tagixo/:

public/vendor/tagixo/
├── builder.js          # Vue 3 builder application (ESM bundle)
├── builder.css         # Builder UI styles
├── chunks/             # Code-split chunks loaded by builder.js
└── fonts/              # PrimeVue icon font and subset web fonts

Re-publish after every package upgrade. The JS bundle version must match the PHP package version. Running composer update ccast/tagixo without re-publishing the assets leaves the frontend out of sync with the server API — builder saves will fail silently or produce schema mismatches.

A one-liner to upgrade and re-publish in one step:

composer update ccast/tagixo && php artisan vendor:publish --tag=tagixo-assets --force

Commit the published assets. If your deployment pipeline runs composer install --no-scripts (e.g., a Dockerfile that bakes the image without running artisan), commit public/vendor/tagixo/ to version control so the files are present in the built image without requiring a post-deploy publish step.

Common first-boot errors

Error Cause Fix
package not found: ccast/tagixo VCS repository entry missing from composer.json Add the repositories block shown above
The "https://github.com/c-cast/tagixo.git" repository could not be cloned PAT missing or expired Set COMPOSER_AUTH or run composer config --global --auth github-oauth.github.com <PAT>
Class "Ccast\Tagixo\TagixoServiceProvider" not found Autoloader not regenerated after install Run composer dump-autoload then php artisan package:discover
Builder UI loads but saving returns 419 CSRF token not present on builder requests Ensure the builder route is inside the web middleware group; see Standalone Integration
Table tgx_pages doesn't exist Migrations not published or not run Run vendor:publish --tag=tagixo-migrations then php artisan migrate
Config changes have no effect on Octane Octane caches the bootstrapped app Run php artisan octane:reload after every config edit
Assets return 404 after upgrade Assets not re-published after composer update Run vendor:publish --tag=tagixo-assets --force

See also