Download the PHP package icetea/icecube without Composer

IceCube

A PHP Single-File Component (SFC) framework for building reactive, component-based web applications. IceCube allows you to write PHP components with colocated styles and JavaScript in a single file, similar to Vue.js Single File Components.

Goals

IceCube aims to provide:

1. Single-File Component Architecture: Write PHP components with their styles and JavaScript in one cohesive file (.ice.php)
2. Component Encapsulation: Scoped styles that don't leak to other components
3. Reactive Client-Side Behavior: Easy-to-use client-side interactivity with a refs-based system
4. Flexible Compilation: Support for different style preprocessors (CSS, SCSS) and bundling strategies (embedded, Vite)
5. Performance Optimization: Automatic compilation, caching, and on-demand loading of components
6. Developer Experience: Intuitive API for creating interactive components without complex build processes
7. Progressive Enhancement: Components work server-side first, with optional client-side enhancements

Architecture

Core Components

1. Component System

• Component: Abstract base class for all components

  • Provides unique ID generation for each component instance
  • Implements SafeStringable interface for seamless HTML rendering
• SingleFileComponent: Extended base class for SFC pattern
  • Automatically extracts public properties as component props
  • Injects component metadata (data-icecube, data-props) into rendered HTML
  • Manages component lifecycle and client-side hydration

2. Parser Layer

• IceCubeParser: Extracts content from .ice.php files

  • Separates PHP code from style and script tags
  • Supports multiple <style> tags with optional global attribute
  • Can parse colocated .js files separately
  • Generates content digest for cache invalidation
• ParsedComponent: Data structure holding parsed component parts

3. Compiler Layer

• IceCubeCompiler: Main compilation orchestrator

  • Scans directories for .ice.php files
  • Manages autoloading of components
  • Compiles components on-demand or in batch
  • Writes compiled files only when changed (optimization)
• CompiledComponent: Container for compiled component artifacts

Style Compilers

Implement the StyleCompiler interface:

• NestingStyleCompiler: Wraps styles with component selector [data-icecube={name}]
• ScssStyleCompiler: Compiles SCSS to CSS with automatic scoping

Script Compilers

Implement the ScriptCompiler interface:

• EmbedStyleScriptCompiler: Embeds styles directly in JavaScript
• ViteScriptCompiler: Imports CSS separately for Vite bundling

4. Registry System

• IceCubeRegistry: Global component registry
  • Stores compiled component metadata
  • Provides cache loading/storing functionality
  • Generates collection of all component styles
  • Injects client-side initialization script

5. Cache System

• CachedComponent: Lightweight cached component data
  • Serializable component metadata for production
  • Supports PHP's var_export for efficient caching

Compilation Flow

Client-Side Runtime

The registry generates JavaScript that:

1. Dynamically imports component scripts on-demand
2. Initializes components via MutationObserver (supports dynamic content)
3. Provides a refs proxy for easy DOM element access
4. Passes component props from server to client
5. Tracks component initialization states (icing → iced)

Style Scoping

Styles are automatically scoped by wrapping them with the component's data attribute:

Global styles (marked with <style global>) bypass scoping.

Usage Guide

Basic Setup (Without Vite)

1. Create a Component

Create a file app/Components/Counter.ice.php:

Alternatively, separate the JavaScript into Counter.js:

2. Initialize the Compiler

In your application bootstrap (e.g., bootstrap/app.php):

3. Render Components in Views

In your Blade template:

4. Production Optimization

For production, use caching:

Advanced Setup (With Vite)

1. Install Required Dependencies

2. Configure Vite

Update vite.config.js to use Vite's glob import for dynamic component loading:

3. Create IceCube Loader Script

Create resources/js/icecube.js:

4. Use icecube.js in your app

In blade template:

Or in icedom

5. Configure Compiler with Vite Strategy

In your application bootstrap or controller:

6. Run Vite Dev Server

With ViteScriptCompiler, compiled JavaScript will import CSS separately:

7. Use NPM Packages in Components

You can import any NPM package in your component JavaScript files:

Laravel Integration Guide

Quick Setup

1. Register Service Provider

Add IceCubeServiceProvider to config/app.php:

Or for Laravel 11+, add to bootstrap/providers.php:

2. Publish Configuration

This creates resources/js/icecube.js where you can customize:

• Component namespace and directories
• Compiler strategies (Vite/Embed, SCSS/CSS)
• Cache settings

3. Create Storage Link

4. Use Components in Blade Views

Service Provider Behavior

The IceCubeServiceProvider automatically:

• Development Mode: Compiles components on-demand via autoloader
• Production Mode: Loads pre-compiled components from cache for maximum performance

Production Build Command

Compile all components and generate cache before deployment:

This CompileIceCubeCommand scans all .ice.php files, compiles them, and stores the cache.

Note: The command automatically detects if you're using ViteScriptCompiler and will skip storing styles in cache (since Vite handles CSS bundling separately).

Add to your deployment script:

Configuration

Configuration in config/icecube.php:

SCSS Import Paths (Optional)

To use SCSS imports like @import './_base.scss', configure in your service provider:

Dynamic Components (HTMX/AJAX)

Components work seamlessly with dynamic content loading:

The icecube.js runtime automatically initializes dynamically added components.

Multiple Compiler Configurations

Configure multiple compilers for different component sets in config/icecube.php:

Compilers are automatically registered in the Laravel container as icecube.compiler.{name} singletons.

Compile All:

Compile Specific:

The IceCubeServiceProvider automatically:

• Registers all compilers in the container
• In development: initializes compilers for on-demand compilation
• In production: loads all caches for maximum performance

Component API

Props System

Public properties are automatically passed to client-side:

Refs System

Use data_ref() to mark elements for easy client-side access:

Component Parameters

• root: The component's root DOM element
• refs: Proxy object for accessing elements with data-ref attributes
• props: Public properties passed from PHP as JSON

Style Scoping

• Regular <style> tags: Scoped to component
• <style global>: Applied globally, not scoped

SCSS Support

To use SCSS, configure the compiler with ScssStyleCompiler:

Then use SCSS syntax in your components:

File Structure

Best Practices

1. Component Organization: Keep components in a dedicated directory (e.g., app/Components)
2. Naming Convention: Use PascalCase for component class names and files
3. Separation of Concerns: For complex JavaScript, use separate .js files
4. Style Scoping: Prefer scoped styles; use global styles sparingly
5. Props Validation: Validate and type-hint public properties
6. Production Builds: Always pre-compile and cache components in production
7. Asset Strategy: Choose between embedded styles or Vite based on your build setup

License

MIT License