Files

Files in Stellify are structured containers that organize methods into cohesive units, representing PHP classes, controllers, models, and other file-based components of your Laravel application.

What are Files?

In traditional development, files are text-based documents containing code. In Stellify, files are JSON definitions that reference methods, providing a structured, queryable representation of your application's organization. This architecture enables:

• Instant refactoring - Move methods between files by updating references
• Surgical updates - Modify specific methods without parsing entire files
• Intelligent organization - Query files by type, purpose, or contained methods
• Parallel development - Multiple developers can work on methods in the same file simultaneously
• AI-native interaction - AI can analyze and modify file structure programmatically

File Structure

A file definition contains references to methods and metadata about its purpose:

{
    "uuid": "file-abc123",
    "name": "UserController",
    "type": "controller",
    "namespace": "App\\Http\\Controllers",
    "path": "app/Http/Controllers/UserController.php",
    "data": [
        "method-uuid-1",     // index()
        "method-uuid-2",     // show()
        "method-uuid-3",     // store()
        "method-uuid-4",     // update()
        "method-uuid-5"      // destroy()
    ],
    "extends": "Controller",
    "implements": [],
    "uses": [
        "App\\Models\\User",
        "Illuminate\\Http\\Request"
    ],
    "statements": [
        "statement-uuid-1"   // File-level statements (rare)
    ]
}

Core Properties

• uuid - Unique identifier for this file
• name - The class/file name (e.g., "UserController")
• type - File type (controller, model, migration, service, etc.)
• namespace - PHP namespace for this file
• path - Relative file path for assembly/export

Composition Properties

• data - Array of method UUIDs that belong to this file
• statements - Array of file-level statement UUIDs (uncommon)

Object-Oriented Properties

• extends - Parent class this file extends
• implements - Interfaces this file implements
• uses - Traits or imports used by this file

File Types

Stellify supports various file types, each with specific purposes and constraints:

Controllers

{
    "type": "controller",
    "name": "UserController",
    "extends": "Controller",
    "data": [/* method UUIDs */]
}

Handle HTTP requests and coordinate application logic

Models

{
    "type": "model",
    "name": "User",
    "extends": "Model",
    "data": [/* method UUIDs for relationships, scopes, etc. */]
}

Represent database tables and define relationships

Migrations

{
    "type": "migration",
    "name": "CreateUsersTable",
    "data": [
        "up-method-uuid",
        "down-method-uuid"
    ]
}

Define database schema changes with specific method requirements (up, down)

Services

{
    "type": "service",
    "name": "PaymentService",
    "data": [/* method UUIDs for business logic */]
}

Encapsulate complex business logic

Seeders & Factories

Special file types for database testing and population

Creating Files

Create a new file through the API:

POST /api/v1/file

{
    "directory": "directory-uuid",
    "name": "ProductController",
    "type": "controller",
    "namespace": "App\\Http\\Controllers"
}

This creates an empty file definition. You then add methods to build out the file's functionality.

Adding Methods to Files

Methods are added by creating them with a reference to the parent file:

POST /api/v1/method

{
    "file": "file-uuid",
    "name": "index",
    "returnType": "view"
}

// The file's data array is automatically updated:
{
    "data": [
        "new-method-uuid"
    ]
}

Method Organization

The order of methods in a file's data array determines their order when the file is assembled. You can reorder methods by updating this array:

PUT /api/v1/file/{uuid}

{
    "data": [
        "method-uuid-3",  // Move third method to first position
        "method-uuid-1",
        "method-uuid-2"
    ]
}

File Assembly

When Stellify assembles your code for execution or export, it:

1. Fetches the file definition
2. Generates the namespace and class declaration
3. Adds extends and implements clauses
4. Assembles each method from the data array
5. Combines everything into executable PHP code

namespace App\Http\Controllers;

class UserController extends Controller
{
    public function index() { /* ... */ }
    public function store() { /* ... */ }
    public function destroy() { /* ... */ }
}

Restricted Files

Some file types have restrictions to maintain framework conventions:

Migrations

• Must have exactly two methods: up() and down()
• Method names are enforced by the system
• Return types must be void

Seeders

• Must have a run() method
• Return type must be void

Factories

• Must have a definition() method
• Return type must be array

File-Level Statements

While rare, files can have statements outside of methods (e.g., global variables, constants). These are stored in the statements array:

{
    "uuid": "file-uuid",
    "name": "config",
    "type": "config",
    "statements": [
        "statement-uuid-1"  // return [...]
    ],
    "data": []  // No methods in config files
}

Duplicating Files

You can duplicate entire files, including all methods, statements, and clauses:

POST /api/v1/file/duplicate

{
    "uuid": "original-file-uuid",
    "directory": "target-directory-uuid"
}

This creates a complete copy with new UUIDs for the file and all its methods.

Searching Files

Query files by various criteria:

GET /api/v1/file/search

?search=User           // Find files containing "User"
&type=controller       // Filter by type
&directory=dir-uuid    // Within specific directory

Moving Methods Between Files

Moving a method from one file to another is a simple reference update:

// 1. Remove from original file
PUT /api/v1/file/{original-file-uuid}
{
    "data": [
        /* method UUIDs without the one you're moving */
    ]
}

// 2. Add to new file
PUT /api/v1/file/{new-file-uuid}
{
    "data": [
        /* existing method UUIDs */,
        "method-uuid-to-move"
    ]
}

No code copying, no text parsing - just reference manipulation.

Relationship to Directories

Files exist within directories, forming a hierarchical structure:

// Directory
{
    "uuid": "directory-uuid",
    "name": "Controllers",
    "data": [
        "file-uuid-1",  // UserController
        "file-uuid-2",  // ProductController
        "file-uuid-3"   // OrderController
    ]
}

// Each file in the directory
{
    "uuid": "file-uuid-1",
    "name": "UserController",
    "data": [/* method UUIDs */]
}

Best Practices

• Follow Laravel conventions - Use standard file types and naming patterns
• Keep files focused - Each file should have a clear, single purpose
• Organize methods logically - Order methods in a way that makes sense for readability
• Use proper namespaces - Follow PSR-4 autoloading standards
• Leverage file types - Use the appropriate type for proper IDE integration
• Don't mix concerns - Controllers handle HTTP, Models handle data, Services handle logic

Exporting Files

Files can be exported as actual PHP files for local development or deployment:

GET /php/{file-uuid}

// Returns assembled PHP code:


namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;

class UserController extends Controller
{
    public function index()
    {
        // Assembled from method definition
    }
}

Version Control Integration

When you make changes to a file (add/remove/reorder methods), Stellify tracks these changes at a granular level:

• Method additions are tracked individually
• Method removals are recorded
• Method reordering is versioned
• You can see exactly what changed and when

This provides much more precise version control than traditional text-based diffing.

You can review the full Files API specification here.