Statements

Statements are logical groupings of clauses that form complete lines of executable code. They represent the building blocks within methods, enabling intelligent code reuse and granular control over program flow.

What are Statements?

In Stellify, a statement is a structured definition that groups one or more clauses into a single executable unit. Think of statements as individual lines of code - assignments, method calls, returns, conditionals, etc. - but stored as JSON with references to their component clauses.

Statements enable powerful features:

• Granular reordering - Move statements within methods without text manipulation
• Intelligent deduplication - Automatically detect and reuse identical code patterns
• Global statement library - Share common code patterns across your codebase
• Precise version control - Track changes at the statement level
• AI-assisted refactoring - AI can analyze and suggest improvements statement-by-statement

Statement Structure

A statement definition includes:

{
    "uuid": "statement-abc123",
    "data": [
        "clause-uuid-1",     // e.g., $total
        "clause-uuid-2",     // e.g., =
        "clause-uuid-3",     // e.g., $price
        "clause-uuid-4",     // e.g., *
        "clause-uuid-5",     // e.g., $quantity
        "clause-uuid-6"      // e.g., ;
    ],
    "code_hash": "7f3a9b2c...",    // SHA-256 hash for deduplication
    "usage_count": 42,              // Times this statement is referenced
    "is_locked": true,              // Part of global library
    "locked_at": "2026-01-10 09:15:00"
}

Core Properties

• uuid - Unique identifier for this statement
• data - Ordered array of clause UUIDs that compose the statement

Deduplication Properties

• code_hash - SHA-256 hash of the assembled code for deduplication
• usage_count - Number of times this exact statement is referenced
• is_locked - When true, statement is part of the global library
• locked_at - Timestamp when statement was locked to global library

How Statements Work

Statements act as containers that organize clauses in a specific order. When Stellify assembles your code for execution, it:

1. Fetches all clauses referenced in the statement's data array
2. Assembles them in order to form the complete PHP code
3. Integrates the assembled code into the parent method

Statement Deduplication

Stellify's statement deduplication system eliminates duplicate code patterns across your entire codebase. When you create a statement, Stellify:

1. Assembles the complete PHP code from the statement's clauses
2. Normalizes the code (removes extra whitespace, standardizes formatting)
3. Computes a SHA-256 hash of the normalized code
4. Checks if a locked statement with this hash already exists
5. If found, references the existing statement instead of creating a duplicate
6. If not found, creates a new statement with the hash for future matching

Benefits of Statement Deduplication

Creating Statements

You can create statements through the API or when using the Code Editor. Here's an API example:

POST /api/v1/statement

{
    "method": "method-uuid",  // The method this statement belongs to
    "file": null              // Or file UUID if statement is file-level
}

This creates an empty statement. You then add clauses to build the actual code:

PUT /api/v1/statement/{uuid}

{
    "uuid": "statement-uuid",
    "data": [
        "clause-uuid-variable",   // $total
        "clause-uuid-equals",     // =
        "clause-uuid-price",      // $price
        "clause-uuid-multiply",   // *
        "clause-uuid-quantity",   // $quantity
        "clause-uuid-semicolon"   // ;
    ]
}

Stellify automatically computes the code_hash and checks for existing matching statements.

Common Statement Types

While statements are generic containers, they typically represent these code patterns:

Assignment Statements

$total = $price * $quantity;

Assigns a value to a variable

Method Call Statements

$user->save();

Calls a method on an object

Return Statements

return $total;

Returns a value from a method

Conditional Statements

if ($total > 100) {

Starts a conditional block

Loop Statements

foreach ($items as $item) {

Iterates over a collection

Statement Reordering

One of the key advantages of storing statements as structured data is the ability to easily reorder them within a method. Simply update the method's data array with the statements in a different order:

PUT /api/v1/method/{uuid}

{
    "data": [
        "statement-uuid-3",  // Moved to first position
        "statement-uuid-1",  // Now second
        "statement-uuid-2"   // Now third
    ]
}

No text parsing, no regex, no risk of syntax errors - just array manipulation.

Preventing Duplication on Import

When importing code from external sources (like copying from GitHub), Stellify's deduplication prevents creating duplicate statements:

1. Code is parsed into statements and clauses
2. Each statement's code is assembled and hashed
3. Existing locked statements with matching hashes are automatically referenced
4. Only truly unique statements are created as new entries

This means importing the same utility function multiple times only stores unique statements once.

Usage Analytics

The usage_count field tracks how many times a statement is referenced across your codebase. This provides valuable insights:

• Identify the most common code patterns in your projects
• Find frequently-used statements that should be locked to the global library
• Understand which patterns are worth optimizing or refactoring
• Help AI prioritize suggesting existing patterns over generating new ones

Locking Statements to Global Library

Highly-reused statements can be locked to become part of your global library, similar to methods. Locked statements:

• Can be referenced across all projects
• Have is_locked: true
• Are prioritized when deduplication checks occur
• Help AI suggest battle-tested patterns

Best Practices

• Keep statements atomic - Each statement should represent one logical operation
• Use meaningful variables - Clear variable names make statements more reusable
• Leverage deduplication - Let Stellify automatically find and reuse existing patterns
• Monitor usage counts - High usage_count indicates patterns worth locking
• Order matters - The order of statements in a method's data array is the execution order

Relationship to Methods

Statements are the building blocks of methods. A method's data array contains an ordered list of statement UUIDs that make up its implementation:

{
    "uuid": "method-uuid",
    "name": "calculateTotal",
    "data": [
        "statement-uuid-1",  // $subtotal = $price * $quantity;
        "statement-uuid-2",  // $tax = $subtotal * 0.1;
        "statement-uuid-3"   // return $subtotal + $tax;
    ]
}

This composable architecture means methods are built from reusable statements, which are in turn built from reusable clauses.

You can review the full Statements API specification here.