ArtiGrid Builder Pro

How Arco and ArtiGrid Builder Pro fit together

This documentation covers two tools that produce the same end result — working ArtiGrid code — through two different workflows.

A common flow: use the Arco wizard or make:crud to scaffold the full page and route, then open the Builder when you want to experiment with extra ArtiGrid features (comboboxes, calendar mode, charts) before folding them back into the generated controller.

Command Overview

Arco is the Artigrid command-line console. Run all commands from the project root:

php arco <command> [arguments] [options]

init

Initializes a new Artigrid project in the current directory. Generates the arco.yaml configuration file and the base folder structure.

Options

Folders created

• artigrid/components — Reusable components
• artigrid/grids — Grid layouts
• artigrid/layouts — Master layouts
• artigrid/pages — Generated pages
• artigrid/interfaces — Full interfaces
• artigrid/styles — Generated base stylesheets
• artigrid/assets — Static assets

# Interactive mode (asks questions)
php arco init
# Non-interactive mode
php arco init --name="My App" --namespace="App\\Artigrid" --style=tailwind
# Overwrite existing configuration
php arco init --force

build

Analyzes all generated artifacts in the project (interfaces, pages, layouts, grids, components) and produces a status report with file count and size per type. Optionally validates file integrity.

Options

# Standard build (generates manifest)
php arco build
# Preview report only, without writing any files
php arco build --dry-run
# Build with file integrity validation
php arco build --validate

db Database

Manages database tables and columns directly from the console. Create, drop, and modify tables without needing a SQL client.

Available actions

Options for create

Options for add-column

# List all tables
php arco db tables
# Show table structure
php arco db show users
# Create a table with all columns in one command
php arco db create employees \
  --columns="name:varchar(100):not_null,email:varchar(200):unique,role:varchar(50)" \
  --timestamps
# Create a table interactively (step by step)
php arco db create products
# Add a column
php arco db add-column users --column=phone --type=varchar(20) --nullable
php arco db add-column users --column=status --type=tinyint --default=1 --after=email
# Drop a column
php arco db drop-column users --column=phone
# Drop a table without confirmation
php arco db drop users --force

nav Navigation

Manages the nav_items database table, which controls the system sidebar menu. Supports root items and multi-level submenus.

Available actions

Options

# View the current menu tree
php arco nav list
# Add a root item
php arco nav add employees --title="Employees" --icon=fa-users
# Add a submenu under an existing parent
php arco nav add active-employees --title="Active" --icon=fa-circle --parent=employees
# Alternative: use add-sub (asks interactively)
php arco nav add-sub employees --title="Inactive" --icon=fa-circle-xmark
# Remove an item (and its children)
php arco nav remove employees
# Reorder items
php arco nav move-up reports
php arco nav move-down settings
# Migrate nav.json to the database
php arco nav migrate
# Empty the entire menu
php arco nav clear

list:templates

Lists all artifacts generated by Arco in the current project, showing filename, size, and last modified date, organized by category.

Options

# List all artifacts
php arco list:templates
# Components only
php arco list:templates --type=components
# Generated pages only
php arco list:templates --type=pages

make:controller Generates files

Generates a PHP Controller, its corresponding View, registers the route in router.php, and adds the item to the sidebar menu. Optionally generates a Model as well.

Arguments and options

Generated files

• app/controllers/NameController.php — With index, create, store, show, edit, update, and destroy methods
• app/views/name/index.php — Basic view (or with ArtiGrid grid if --with-grid)
• app/models/NameModel.php — Only if --with-model is used
• Route registered in app/core/router.php
• Item added to nav_items in the database (or nav.json as fallback)

# Basic controller
php arco make:controller Employees --icon=fa-users
# With an ArtiGrid grid connected to a table
php arco make:controller Products --with-grid --table=products --icon=fa-box
# With grid and model
php arco make:controller Clients --with-grid --table=clients --with-model --icon=fa-building
# Without registering in the sidebar menu
php arco make:controller Reports --no-nav

make:model Generates files

Generates a standalone PHP Model with complete CRUD methods: all(), find(), where(), create(), update(), delete(), count(), and paginate().

Options

Included methods

• all(string $orderBy, string $dir) — Fetches all records with configurable ordering
• find(int $id) — Finds a record by ID
• where(string $field, mixed $value) — Filters records by a field value
• create(array $data) — Inserts a record, returns the new ID
• update(int $id, array $data) — Updates a record
• delete(int $id) — Deletes a record
• count() — Returns the total number of records
• paginate(int $page, int $perPage) — Returns a page with full pagination metadata

# Model with automatically inferred table name (employees)
php arco make:model Employee
# Model with an explicit table name
php arco make:model Product --table=products

make:view Generates files

Generates a PHP view inside app/views/. Supports three variants: basic, with an ArtiGrid grid placeholder, or with an HTML table.

Options

# Basic view
php arco make:view employees/detail --title="Employee Detail"
# View with an ArtiGrid grid placeholder
php arco make:view reports/sales --with-grid
# View with a dynamic HTML table
php arco make:view dashboard/index --with-table

make:crud Generates files

Generates a complete PHP page with an ArtiGrid CRUD interface for a database table. The most feature-rich command: supports column selection, renaming, field types, comboboxes, validation, WHERE filters, JOINs, nested tables, exports, and more.

Main options

# Basic CRUD
php arco make:crud Users users
# With selected columns and modal forms
php arco make:crud Products products --columns=id,name,price,stock --modal
# With renaming, combobox, and export
php arco make:crud Employees employees \
  --columns=id,name,email,department_id,status,hire_date \
  --rename=name=Name \
  --rename=department_id=Department \
  --rename=hire_date="Hire Date" \
  --field-type=status=select \
  --field-type=hire_date=date \
  --combobox=department_id=departments:id:name \
  --required=name,email \
  --export=excel,csv \
  --modal
# With WHERE filter and sorting
php arco make:crud Orders orders \
  --where=status==pending \
  --order-by=created_at \
  --order-dir=desc \
  --per-page=20
# With nested child table
php arco make:crud Clients clients \
  --nested="Orders=id:orders:client_id"
# With JOIN
php arco make:crud Users users \
  --join=role_id=roles:id:LEFT \
  --columns=name,email,roles_name
# Read-only with export
php arco make:crud Reports orders --mode=readonly --export=excel,pdf

make:dashboard Generates files

Generates a PHP dashboard with a sidebar, multiple ArtiGrid grids, and optional authentication support. Define several tables that will be displayed as independent sections.

Options

# Dashboard with two grids
php arco make:dashboard AdminPanel --grids=users:Users,orders:Orders
# Dashboard with auth guard
php arco make:dashboard Panel --grids=employees:Employees --with-auth
# Interactive mode (asks grid by grid)
php arco make:dashboard MyPanel

make:stats Generates files

Generates a complete stats panel with: metric cards (table row counts), a monthly activity chart using ArtiGrid + Chart.js, and a recent records table. Automatically registers the Controller, View, and route.

Options

# Full stats panel
php arco make:stats Dashboard \
  --metrics=users:Users:fa-users,orders:Orders:fa-cart-shopping,products:Products:fa-box \
  --chart-table=orders --chart-date=created_at --chart-type=line \
  --recent-table=users --recent-cols=name,email,created_at
# Minimal panel with a single metric
php arco make:stats Summary --metrics=admin_users:Admins:fa-user-shield

make:login Generates files

Generates a complete authentication system with three files: a login page, a logout handler, and an auth guard.

Options

Generated files

• pages/login.php — ArtiGrid login form
• pages/logout.php — Destroys the session and redirects
• pages/auth.php — Guard: include at the top of protected pages

# Basic login with defaults
php arco make:login
# Custom login
php arco make:login --table=users --user=email --password=password --redirect=dashboard.php
# Login with role-based access control
php arco make:login --roles=admin,editor
# Protecting a page with the generated guard:
# Add this line at the top of the PHP file:
require_once 'auth.php';

make:component Generates files

Generates a reusable Artigrid component. Supports multiple base types, props, slots, style variants, and optionally a PHP component class.

Available component types

card, nav, modal, table, form, button, badge, alert, dropdown, tabs, hero, sidebar, header, footer, widget

Options

# User card component
php arco make:component UserCard --type=card --props=name,avatar,role,email
# Navigation bar with slots and variants
php arco make:component NavBar --type=nav --slots=brand,links,actions --variants=light,dark
# Data table with PHP class
php arco make:component DataTable --type=table --props=columns,rows,sortable --php-class

make:grid Generates files

Generates a reusable CSS grid layout. Supports simple grids, named grid-areas, and responsive breakpoint variants.

Options

# Responsive 2-column grid
php arco make:grid TwoColumn --columns=2 --gap=2rem --responsive
# Dashboard with named areas
php arco make:grid Dashboard --areas="header header / sidebar main / footer footer"
# Masonry-style grid
php arco make:grid Masonry --columns=3 --rows=0

make:layout Generates files

Generates a reusable master layout with predefined content regions. Includes presets for the most common application types.

Type presets and their default regions

php arco make:layout App --type=app --regions=header,main,aside,footer
php arco make:layout Marketing --type=marketing
php arco make:layout Auth --type=auth

make:interface Generates files

Generates a complete large interface with grids, sections, and components. Unlike make:layout, it generates the full visual structure with content sections already in place.

Default sections by type

php arco make:interface Dashboard --type=dashboard --with-nav --with-sidebar
php arco make:interface AdminPanel --type=admin --sections=header,sidebar,main,footer
php arco make:interface LandingPage --type=landing --columns=12

make:page Generates files

Generates a complete Artigrid page tied to an existing layout, with URL route support and SEO meta tags.

Options

php arco make:page Home --layout=marketing --title="Welcome" --with-meta
php arco make:page UserProfile --layout=app --route="/users/{id}"

make:nav-manager Navigation Generates files

Generates a full web-based manager for the sidebar menu (nav_items). Create, edit, delete, and reorder menu items directly from the browser without touching the database manually.

Options

Web manager features

• Table listing all menu items with hierarchy indicators (└─ for submenus)
• Modal for creating new items (slug, title, icon, optional parent)
• Modal for editing existing items (with active/inactive toggle)
• Move up/down buttons to reorder items within their level
• Delete with confirmation (warns if the item has child submenus)

# With defaults
php arco make:nav-manager
# With custom URL and title
php arco make:nav-manager --url=menu --title="System Menu"

make:wizard Interactive Database

A step-by-step interactive assistant for creating a complete CRUD manager. Guides the user through numbered questions, can create the database table if it does not exist, and generates all MVC files in a single session.

Wizard steps

Generated files

• app/controllers/NameController.php
• app/views/name/index.php
• app/models/NameModel.php — Only if selected in step ⑭
• database/migrations/YYYY_MM_DD_HHmmss_create_table_name_table.sql — Only if a new table was created
• Route registered in app/core/router.php
• Item added to the menu in the database or nav.json

Available column types when creating a table

string (VARCHAR 255), text, integer, bigint, decimal (10,2), boolean, date, datetime, time, json, float

php arco make:wizard

Introduction Visual Builder

ArtiGrid Builder Pro is a visual code generator that creates PHP code for ArtiGrid CRUD interfaces without manual coding. It provides an intuitive drag-and-drop interface where you configure database tables, fields, validation rules, and rendering modes—then instantly generates production-ready PHP code.

What Problems Does It Solve?

• Eliminates repetitive PHP boilerplate code for CRUD operations
• Allows non-developers to create database interfaces visually
• Enables rapid prototyping and iteration of forms and grids
• Supports multiple render modes (table, form, calendar, login, chart)
• Generates production-ready code with proper validation and security practices
• Integrates seamlessly with your existing ArtiGrid configuration

How ArtiGrid Builder Works

ArtiGrid Builder follows a simple workflow:

Interface Components

The Builder interface is divided into three main areas:

Five Render Modes

ArtiGrid Builder supports five different rendering modes, each designed for specific use cases:

CRUD Mode

CRUD (Create, Read, Update, Delete) mode generates a complete data management interface with a sortable, filterable data grid and built-in forms for editing records.

Features Available

• Table selection from database
• Column visibility toggling
• Form field arrangement and grouping
• Required field validation
• Action button configuration (view, edit, delete)
• Button arrangement (dropdown or inline)
• Search and filter panel
• Pagination and per-page settings
• Inline editing (optional)
• Modal vs. inline form rendering
• Column rename and field type customization
• Combobox (dropdown) configuration
• Custom button creation
• Export functionality (Excel, CSV, PDF)

Configuration Steps

1. Select Table: Choose your database table from the dropdown
2. Choose Columns: Select which columns appear in the grid
3. Define Form Fields: Pick fields that appear in insert/edit forms
4. Set Validation: Mark fields as required or add custom validation
5. Configure Actions: Choose which actions (view, edit, delete) are enabled
6. Review Code: Copy the generated PHP code

$grid = new ArtiGrid();
$grid->table('employees')
    ->template('bootstrap5')
    ->perPage(10)
    ->required(false)
    ->validation_required(['firstName','lastName'])
    ->crudCol(['employeeNumber','firstName','lastName','email'])
    ->formFields(['employeeNumber','firstName','lastName','email','officeCode'])
    ->modal();
echo $grid->render();

Form Mode (Insert Only)

Form mode generates a standalone insert form without displaying the data grid. This is ideal for dedicated data entry pages or when you want to focus the user's attention on completing a form.

Use Cases

• Multi-step registration or onboarding processes
• Dedicated survey or feedback forms
• Order entry pages
• Invoice or invoice line item creation
• Custom workflows where grid view is not needed

Configuration Options

$grid = new ArtiGrid();
$grid->table('orders')
    ->template('bootstrap5')
    ->required(false)
    ->validation_required(['customerNumber','orderDate','status'])
    ->formFields(['customerNumber','orderDate','status','comments'])
    ->modal();
echo $grid->render('insert');

Calendar Mode

Calendar mode generates an interactive calendar interface for tables with date fields, like events, appointments, or tasks. It supports drag-and-drop, color coding, and custom color pickers.

Essential Configuration

Color Picker Configuration

Enable the optional color picker for users to assign colors to events:

• Color Palette: Define available colors (space-separated hex codes)
• Picker Position: Choose between "fixed" (for modals) or default positioning
• Default Colors: Pre-defined palette: #3788d8, #28a745, #dc3545, #fd7e14

$grid = new ArtiGrid();
$grid->table('appointments')
    ->template('bootstrap5')
    ->calendarTitle('title')
    ->calendarStart('start_date')
    ->calendarEnd('end_date')
    ->calendarColor('color')
    ->calendarAllDay('all_day')
    ->calendarView('dayGridMonth')
    ->calendarLocale('en')
    ->colorPicker('color', ['#3788d8','#28a745','#dc3545'], 'fixed');
echo $grid->render('calendar');

Login Mode

Login mode generates a user authentication form that validates credentials against a database table. It supports custom HTML styling and optional server-side validation callbacks.

Configuration Options

• Username Field: Column containing usernames or email addresses
• Password Field: Column with hashed passwords
• Form Template: Custom HTML layout for the login form
• Validation Callback: Server-side login logic (optional)
• Success Redirect: URL to navigate to after successful login

Optional Features

$grid = new ArtiGrid();
$grid->table('users')
    ->template('bootstrap5')
    ->required(false)
    ->validation_required(['username','password'])
    ->formFields(['username','password']);
echo $grid->render('select');

Chart Mode

Chart mode generates data visualizations from your database. It supports multiple chart types and dynamic SQL-based datasets, allowing you to create real-time dashboards without extra charting libraries.

Supported Chart Types

• Bar Chart: Compare values across categories
• Line Chart: Show trends over time
• Pie Chart: Display proportions and percentages
• Doughnut Chart: Similar to pie with a centered hole
• Radar Chart: Compare multiple variables around a central axis
• Polar Area Chart: Show values as radial areas

Dataset Configuration

Each chart can have multiple datasets. For each dataset you configure:

Dynamic SQL Datasets

You can load chart data directly from the database by prefixing the query with a hash (#):

# Example: Dynamic dataset
#select SUM(amount) from orders where orderDate >= DATE_SUB(NOW(), INTERVAL 30 DAY)

$grid = new ArtiGrid();
$grid->table('sales')
    ->template('bootstrap5');
$grid->chart_labels(
    ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
    [
        [
            'label' => 'Sales Volume',
            'data' => '#select COUNT(*) from sales where MONTH(date) IN (1,2,3,4,5)',
            'backgroundColor' => 'rgba(55, 136, 216, 0.2)',
            'borderColor' => 'rgba(55, 136, 216, 1)',
            'borderWidth' => 1
        ]
    ],
    'bar'
);
$grid->chart_view(true);
echo $grid->render();

Code Generation & Export

After configuring your settings, ArtiGrid Builder generates production-ready PHP code that you can immediately use in your application.

The Generated Code Includes

• ArtiGrid class instantiation
• Table/database selection
• Column configuration (visible columns, form fields)
• Validation rules (required fields, custom validations)
• UI customization (template, button arrangement, modals)
• Mode-specific configuration (calendar fields, chart data, etc.)
• Render call with appropriate mode and parameters

Copying and Using Generated Code

1. Click the "Copy Code" button in the preview area
2. Paste into your PHP file that requires ArtiGrid.php
3. Ensure your database credentials are configured in your db.php
4. Test the generated interface in your browser
5. Customize further using ArtiGrid methods if needed

Best Practices

1. Start Simple, Then Extend

Use the Builder to generate the basic CRUD grid, then enhance it with advanced features using direct ArtiGrid method calls in your code.

2. Validate Field Types

Ensure your database schema has appropriate column types (VARCHAR, DATE, INT, etc.) so the Builder can correctly infer validation rules and input types.

3. Plan Form Field Grouping

Before generating code, decide which fields belong together logically. Use the Builder's field arrangement feature to organize them into sections.

4. Use Modal Forms for CRUD

For standard CRUD operations, enable modal forms to keep users focused on the grid without page navigation.

5. Test Generated Code Immediately

Copy the generated code and test it right away to ensure it works in your environment before making further modifications.

6. Keep Builder Configuration Stable

Avoid frequently switching tables in the Builder. Generate code for one table at a time, and organize your generated scripts logically in your project.

7. Combine with ArtiGrid Methods

The Builder generates basic code. Enhance it with ArtiGrid's advanced features:

• combobox() for relational dropdowns
• fieldCondition() for dynamic field visibility
• setActionCondition() for conditional button display
• callbacks() for custom validation logic
• nestedTable() for multi-level hierarchies

Security Considerations

Protecting the Builder

Always follow these security practices when deploying ArtiGrid Builder:

1. Restrict Access: Place the Builder behind user authentication. Only developers should access it.
2. Development Environment Only: Use the Builder only in development or staging environments, never in production.
3. Database Credentials: Ensure your db.php file uses secure, limited credentials—not the production admin account.
4. Rename the Builder: Consider renaming builder.php to something non-obvious, or use a URL rewrite to limit access.
5. Disable in Production: Remove or disable the Builder entirely from production deployments.
6. Access Logs: Monitor access logs for unauthorized Builder usage attempts.

Generated Code Security

The generated code itself follows best practices:

• Uses prepared statements (ArtiGrid handles parameterized queries internally)
• Implements CSRF protection through ArtiGrid's session handling
• Supports role-based access control via callbacks and permissions
• Validates input using configurable required-field rules
• Does not expose sensitive database structures to end users

Additional Recommendations

• Always validate and sanitize user input server-side using callbacks
• Implement proper session management and timeout policies
• Use HTTPS to encrypt data in transit
• Regularly update ArtiGrid to the latest secure version
• Test generated forms for XSS vulnerabilities before deployment
• Implement rate limiting on sensitive operations (delete, bulk edit)