Compiler Repr Semantics

May 19, 2026 · View on GitHub

Goal

The repr layer defines the compiler's internal data model.

Its job is simple:

store parsed export metadata
remain stable across parser and builder changes
provide a common language for the compiler pipeline

It should be read as:

AST has already been interpreted, but final code has not been generated yet.

Files

vphp/compiler/repr/
  common.v
  class.v
  interface.v
  enum.v
  function.v
  constant.v
  globals.v
  task.v

Base Repr

`PhpRepr`

Defined in common.v.

This is the common sum-like umbrella interface used by the compiler pipeline:

Compiler.elements []PhpRepr
linker passes
export collection

It is intentionally empty.

Its value is only in allowing heterogeneous compiler elements to be stored in one slice.

Class Repr

Defined in class.v.

`PhpClassRepr`

Represents one PHP-visible class exported from a V struct.

Fields:

name
- Original V struct name
- Example: Article
php_name
- Final PHP-visible class name
- May include namespace segments
- Example: VPhp\\Task
parent
- PHP parent class name used for inheritance export
- Empty string means no parent
is_final
- Whether the class should be emitted as final
- Currently mostly reserved for future expansion
is_abstract
- Whether the class should be emitted as abstract
- Consumed by the builder/emitter layer to set Zend flags
embeds_v
- Raw V-side embedded struct names
- Preserved so linker can decide whether an embed should become:
  - PHP inheritance
  - future trait expansion
  - or remain V-only composition
implements_v
- Explicit V-side implements declarations as parsed from the struct
- This preserves the V-side source-of-truth relationship
implements
- Resolved PHP-visible interface names after linker reconciliation
- This is the nominal PHP-side relationship list used by emission
shadow_const_name
- Name of the V-side shadow constant binding
- Example: article_consts
- This is a lookup key, not the type
shadow_static_name
- Name of the V-side shadow static binding
- Example: article_statics
- Also a lookup key, not the type
shadow_const_type
- Resolved V type name behind shadow_const_name
- Filled during linking, not during initial parse
shadow_static_type
- Resolved V type name behind shadow_static_name
- Filled during linking
constants
- Class constants that should exist on the emitted PHP class
- Contains both directly declared constants and linked shadow constants
properties
- PHP-visible class properties
- Includes instance properties
- May also include linked static properties derived from shadow statics
methods
- PHP-visible method metadata

`PhpClassConstRepr`

Represents one PHP class constant.

Fields:

name
- PHP constant name
- Example: MAX_TITLE_LEN
v_field_name
- Original V field name if the constant came from a shadow struct
- Useful for traceability
value
- Literal string form used during code generation
const_type
- Semantic type used by builder/emitter
- Common values:
  - int
  - long
  - double
  - string
  - bool

`PhpClassPropRepr`

Represents one PHP property.

Fields:

name
- Final PHP property name
v_type
- Original V-side type name
- Used for bridge code generation and runtime conversion
visibility
- One of:
  - public
  - protected
  - private
is_static
- Whether this property should be declared as a PHP static property
- For shadow statics, this is filled during linking

`PhpMethodRepr`

Represents one PHP-visible method.

Fields:

name
- Final PHP method name
- Example: create, save, __construct
v_name
- Original V method/function name
- Needed because PHP and V method names may diverge
v_c_func
- Underlying exported V C symbol name
- Useful when wrapper generation needs stable symbol mapping
is_static
- Whether the method is a PHP static method
return_type
- Return type in V terms
- Examples:
  - void
  - bool
  - string
  - &Article
args
- Ordered argument metadata
has_export
- Whether this method already has a custom export path
- Used to skip generating default wrappers in some cases
visibility
- PHP visibility string
is_abstract
- Whether the method should be emitted as abstract

`PhpArgRepr`

Used by both functions and methods.

Fields:

name
- Parameter name
v_type
- Original V-side parameter type

Function Repr

Defined in function.v.

`PhpFuncRepr`

Represents one PHP-visible free function exported from V.

Fields:

name
- Final PHP-visible function name
original_name
- Original V function name
return_type
- Original V return type
- This is semantic V type information, not a direct signal that the emitter should build a PHP object wrapper
args
- Ordered parameter metadata
is_internal
- Reserved for internal/compiler-managed exports

Notes:

user-facing free functions are sourced from @[php_function]
the generated PHP entry always calls the generated V wrapper
that wrapper is responsible for reading Context, calling the original V function, and writing the return value

Interface Repr

Defined in interface.v.

`PhpInterfaceRepr`

Represents one PHP-visible interface.

Fields:

name
- Original V interface name
php_name
- Final PHP-visible interface name
methods
- Interface method contracts

Notes:

Interface methods reuse PhpMethodRepr
At this stage, methods are contracts, not implementations

Enum Repr

Defined in enum.v.

`PhpEnumRepr`

Represents one PHP-visible enum-style export.

Fields:

name
- Original V enum name
php_name
- PHP-visible enum class name
cases
- Enum cases, stored as PhpEnumCaseRepr
parse_err
- Deferred parse error slot
- Used when enum syntax is discovered but cannot be safely exported

`PhpEnumCaseRepr`

Fields:

name
- Final exported case name
value
- Literal string value used by code generation

Function Repr

Defined in function.v.

`PhpFuncRepr`

Represents one PHP global function export.

Fields:

name
- Final PHP-visible function name
original_name
- Original V function name when PHP export name differs
return_type
- V-side return type
- The emitter still needs to classify whether this is an object return or a scalar/container return
args
- Ordered argument metadata
is_internal
- Internal-use flag
- Mostly a policy/control field
- Used to distinguish wrapper strategy

Constant Repr

Defined in constant.v.

`PhpConstRepr`

Represents one global constant-like export or one shadow constant carrier.

Fields:

name
- Exported name or shadow lookup name
value
- Literal string value
- Mainly used for scalar constants
const_type
- Semantic constant type
- Examples:
  - int
  - f64
  - string
  - bool
  - struct
v_type
- Original V-side type name
- Especially important when const_type == 'struct'
has_php_const
- Whether this constant should become a PHP global constant
- Shadow carriers may intentionally be false
fields
- Nested sub-constants when the constant represents a struct-like constant carrier
- Used by class shadow constant linking