PHPackages                             icetea/icecube - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. icetea/icecube

ActiveLibrary[Utility & Helpers](/categories/utility)

icetea/icecube
==============

Ice Component system for PHP, using IceCube

0.2.2(6mo ago)03MITPHPPHP ^8.1

Since Nov 7Pushed 6mo agoCompare

[ Source](https://github.com/khanhicetea/icecube)[ Packagist](https://packagist.org/packages/icetea/icecube)[ Docs](https://github.com/icetea/icecube)[ RSS](/packages/icetea-icecube/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (5)Versions (6)Used By (0)

IceCube
=======

[](#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
-----

[](#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
------------

[](#architecture)

### Core Components

[](#core-components)

#### 1. Component System

[](#1-component-system)

- **[`Component`](src/Component.php)**: Abstract base class for all components

    - Provides unique ID generation for each component instance
    - Implements `SafeStringable` interface for seamless HTML rendering
- **[`SingleFileComponent`](src/SingleFileComponent.php)**: 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

[](#2-parser-layer)

- **[`IceCubeParser`](src/Parser/IceCubeParser.php)**: Extracts content from `.ice.php` files

    - Separates PHP code from style and script tags
    - Supports multiple `` tags with optional `global` attribute
    - Can parse colocated `.js` files separately
    - Generates content digest for cache invalidation
- **[`ParsedComponent`](src/Parser/ParsedComponent.php)**: Data structure holding parsed component parts

#### 3. Compiler Layer

[](#3-compiler-layer)

- **[`IceCubeCompiler`](src/Compiler/IceCubeCompiler.php)**: 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`](src/Compiler/CompiledComponent.php)**: Container for compiled component artifacts

##### Style Compilers

[](#style-compilers)

Implement the [`StyleCompiler`](src/Compiler/StyleCompiler.php) interface:

- **[`NestingStyleCompiler`](src/Compiler/NestingStyleCompiler.php)**: Wraps styles with component selector `[data-icecube={name}]`
- **[`ScssStyleCompiler`](src/Compiler/ScssStyleCompiler.php)**: Compiles SCSS to CSS with automatic scoping

##### Script Compilers

[](#script-compilers)

Implement the [`ScriptCompiler`](src/Compiler/ScriptCompiler.php) interface:

- **[`EmbedStyleScriptCompiler`](src/Compiler/EmbedStyleScriptCompiler.php)**: Embeds styles directly in JavaScript
- **[`ViteScriptCompiler`](src/Compiler/ViteScriptCompiler.php)**: Imports CSS separately for Vite bundling

#### 4. Registry System

[](#4-registry-system)

- **[`IceCubeRegistry`](src/IceCubeRegistry.php)**: 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

[](#5-cache-system)

- **[`CachedComponent`](src/Cache/CachedComponent.php)**: Lightweight cached component data
    - Serializable component metadata for production
    - Supports PHP's `var_export` for efficient caching

### Compilation Flow

[](#compilation-flow)

```
.ice.php file
    ↓
IceCubeParser
    ↓
ParsedComponent (PHP + Styles + JS)
    ↓
IceCubeCompiler
    ├→ StyleCompiler → compiled.css
    ├→ ScriptCompiler → compiled.js (with styles)
    └→ PHP class → compiled.php
    ↓
CompiledComponent
    ↓
IceCubeRegistry

```

### Client-Side Runtime

[](#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

[](#style-scoping)

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

```
/* Original */
.button {
  color: red;
}

/* Compiled (Nesting) */
[data-icecube="App_Components_Counter"] {
  .button {
    color: red;
  }
}

/* Or with SCSS compiler */
[data-icecube="App_Components_Counter"] .button {
  color: red;
}
```

Global styles (marked with ``) bypass scoping.

Usage Guide
-----------

[](#usage-guide)

### Basic Setup (Without Vite)

[](#basic-setup-without-vite)

#### 1. Create a Component

[](#1-create-a-component)

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

```