Marko PHP Framework

The Marko documentation is organized into five distinct sections based on the developer's journey. Knowing which section to consult helps you find the right level of detail:

1. Getting Started: Linear, sequential onboarding for new developers (e.g., Installation, Project Structure).
2. Concepts: Explains the why behind the architecture and design decisions (e.g., Modularity, Dependency Injection). It does not contain step-by-step instructions.
3. Packages (Reference): The single source of truth for individual Composer packages. It provides full API references, configuration details, and installation commands.
4. Guides (How-To): Task-oriented instructions for accomplishing specific goals that might span multiple packages (e.g., "How to set up authentication").
5. Tutorials: End-to-end, project-oriented builds that guide you from composer create-project to a finished, working application.

A plugin is a class that intercepts the input or output of a public method on another class without replacing that class. It is Marko's fine-grained extensibility primitive. Plugins are automatically discovered from any module's src/ directory; no manual registration is required.

When to use

Use a plugin when you need to modify arguments to, or the result from, a public method on a class without rewriting or subclassing it. Common use cases include:

• Enriching a return value
• Validating or transforming inputs before the method runs
• Short-circuiting (e.g., returning a cached result or a guard/redirect)
• Logging or observing method calls
• Chaining transformations across modules

Note: If you need to perform a total replacement of a class, use a Preference instead. Plugins and Preferences are complementary: Plugins modify behavior, while Preferences swap entire implementations.

Relationships are defined using property attributes on your Entity classes. Marko does not support lazy loading; all related entities must be loaded explicitly via eager loading.

/**
 * HasOne: The foreignKey is the property name on the RELATED entity pointing back to this one.
 */
#[HasOne(entityClass: Profile::class, foreignKey: 'userId')]
public ?Profile $profile = null;

/**
 * HasMany: The foreignKey is the property name on the RELATED entity pointing back to this one.
 */
#[HasMany(entityClass: Comment::class, foreignKey: 'postId')]
public EntityCollection $comments;

/**
 * BelongsTo: The foreignKey is the property name on THIS entity pointing to the related entity.
 */
#[BelongsTo(entityClass: Post::class, foreignKey: 'postId')]
public ?Post $post = null;

/**
 * BelongsToMany: Uses a pivot entity.
 * foreignKey: pivot property pointing to THIS entity.
 * relatedKey: pivot property pointing to the RELATED entity.
 */
#[BelongsToMany(
    entityClass: Tag::class,
    pivotClass: PostTag::class,
    foreignKey: 'postId',
    relatedKey: 'tagId',
)]
public EntityCollection $tags;

Marko uses three distinct layers to provide context to AI agents. Choosing the right layer depends on what kind of help you are trying to provide.

The Three Layers

1. LSP (Language Server Protocol): Provides factual code intelligence. It answers "what is in the code right now?" (e.g., completions, definitions, hover). Triggered by editor actions like typing or hovering.
2. MCP (Model Context Protocol): Provides capabilities and lookups. It answers "do this thing or look this up" (e.g., searching for a plugin, validating a module). Triggered when an agent decides it needs runtime information.
3. Skills: Provides workflows and conventions. It answers "how do I do X the Marko way?" (e.g., a multi-step process to create a module). Triggered when an agent matches a user request to a skill's description.

Decision Matrix for adding new help