Zephir

https://github.com/zephir-lang/zephir
Admin
Zephir is a high-level programming language that simplifies the creation and maintenance of PHP...
Tokens:7,090
Snippets:69
Trust Score:9.1
License:MIT
Update:9 months ago
Show doc for...
Tokens:
Raw
### Installing Zephir using Composer

Source: https://github.com/zephir-lang/zephir/blob/development/WINDOWS.md

Steps to install Zephir after cloning or downloading the repository. It involves navigating to the Zephir directory and running Composer to install its dependencies.

```cmd
cd c:\path-to-zephir
composer install
```

--------------------------------

### Building Zephir Extension

Source: https://github.com/zephir-lang/zephir/blob/development/WINDOWS.md

Commands to build a Zephir extension. After setting up the development environment and changing to the extension's directory, `zephir build` compiles the extension.

```cmd
%PHP_SDK%\bin\phpsdk_setvars
CD to your extension and zephir build
```

--------------------------------

### Build and Install Zephir Extension (Bash)

Source: https://context7.com/zephir-lang/zephir/llms.txt

Performs the full workflow of generating C code, compiling it, and installing the extension. Supports development mode and parallel compilation.

```bash
# Full build and install workflow
zephir build

# Build in development mode
zephir build --dev

# Build with parallel compilation
zephir build -j 4

```

--------------------------------

### Zephir Static Methods and Properties Example

Source: https://context7.com/zephir-lang/zephir/llms.txt

Demonstrates the use of static methods and properties in Zephir, including late static binding. It shows how to define static variables and methods that can be accessed directly on the class.

```zep
namespace MyExtension;

class StaticExample
{
    protected static instances = 0;
    protected static config = [];

    public static function getInstance()
    {
        var className, fullClassName;

        let className = get_called_class();
        let fullClassName = "\" . className;
        let self::instances++;

        return new {fullClassName}();
    }

    public static function setConfig(string key, var value) -> void
    {
        let self::config[key] = value;
    }

    public static function getConfig(string key) -> var
    {
        if isset self::config[key] {
            return self::config[key];
        }

        return null;
    }

    public static function getInstanceCount() -> int
    {
        return self::instances;
    }
}
```

--------------------------------

### Setting PHP SDK Environment Variable

Source: https://github.com/zephir-lang/zephir/blob/development/WINDOWS.md

Command to set the PHP_SDK environment variable, pointing to the extracted PHP SDK directory. This is crucial for utilizing the PHP SDK tools for building.

```cmd
setx php_sdk "c:\path-to-php-sdk"
```

--------------------------------

### Setting Windows Environment Path

Source: https://github.com/zephir-lang/zephir/blob/development/WINDOWS.md

Commands to update the system's PATH environment variable to include directories for PHP and Zephir. This ensures that these executables can be run from any command prompt.

```cmd
setx path "%path%;c:\path-to-php\"
setx path "%path%;c:\path-to-zephir"
```

--------------------------------

### Zephir Constants and Class Constants Example

Source: https://context7.com/zephir-lang/zephir/llms.txt

Demonstrates how to define and use constants at both the class level and namespace level in Zephir. It shows examples of defining various types of constants and accessing them within class methods.

```zep
namespace MyExtension;

class Constants
{
    const VERSION = "1.0.0";
    const DEFAULT_TIMEOUT = 30;
    const ALLOWED_TYPES = ["text", "html", "json"];

    public function getVersion() -> string
    {
        return self::VERSION;
    }

    public function getTimeout() -> int
    {
        return self::DEFAULT_TIMEOUT;
    }

    public function isTypeAllowed(string type) -> bool
    {
        return in_array(type, self::ALLOWED_TYPES);
    }
}
```

--------------------------------

### Zephir Array Operations Example

Source: https://context7.com/zephir-lang/zephir/llms.txt

Provides examples of common array manipulations in Zephir, including creating, appending, updating, fetching, merging, and filtering arrays. It showcases Zephir's syntax for array handling.

```zep
namespace MyExtension;

class ArrayOperations
{
    public function createArray() -> array
    {
        var myArray;

        let myArray = [
            "name": "John",
            "age": 30,
            "active": true
        ];

        return myArray;
    }

    public function appendToArray(array! items, var item) -> array
    {
        let items[] = item;
        return items;
    }

    public function updateArray(array! data, string key, var value) -> array
    {
        let data[key] = value;
        return data;
    }

    public function fetchFromArray(array! data, string key) -> var
    {
        var value;

        if fetch value, data[key] {
            return value;
        }

        return null;
    }

    public function mergeArrays(array! first, array! second) -> array
    {
        return array_merge(first, second);
    }

    public function filterArray(array! items) -> array
    {
        var item;
        array result = [];

        for item in items {
            if item > 10 {
                let result[] = item;
            }
        }

        return result;
    }
}
```

--------------------------------

### Install Zephir Extension (Bash)

Source: https://context7.com/zephir-lang/zephir/llms.txt

Installs the compiled Zephir extension into the PHP extension directory. May require superuser privileges. Supports installation in development mode.

```bash
# Install the extension (may require sudo)
zephir install

# Install in development mode
zephir install --dev

```

--------------------------------

### Configuring Zephir Parser Extension in php.ini

Source: https://github.com/zephir-lang/zephir/blob/development/WINDOWS.md

Instructions for enabling the Zephir Parser extension in PHP. This involves adding a specific line to the php.ini configuration file, pointing to the `zephir_parser.dll`.

```ini
[Zephir Parser]
; You can use here absolute path to your custom modules dir
; or relative to the PHP modules dir
extension=zephir_parser.dll
```

--------------------------------

### Zephir Exception Handling Example

Source: https://context7.com/zephir-lang/zephir/llms.txt

Shows how to implement exception handling using try-catch-finally blocks in Zephir. It includes handling specific exceptions like `InvalidArgumentException` and `RuntimeException`, as well as a general `Exception`, and demonstrates the use of a finally block for cleanup.

```zep
namespace MyExtension;

class ExceptionHandling
{
    public function riskyOperation() -> string
    {
        try {
            var result;

            let result = this->doSomethingRisky();

            return result;
        } catch \InvalidArgumentException, e {
            return "Invalid argument: " . e->getMessage();
        } catch \RuntimeException, e {
            return "Runtime error: " . e->getMessage();
        } catch \Exception, e {
            return "General error: " . e->getMessage();
        } finally {
            // Cleanup code runs regardless
            this->cleanup();
        }
    }

    public function throwCustomException() -> void
    {
        throw new \InvalidArgumentException("Custom error message");
    }

    protected function doSomethingRisky() -> string
    {
        return "success";
    }

    protected function cleanup() -> void
    {
        // Cleanup logic
    }
}
```

--------------------------------

### Zephir Interfaces and Abstract Classes Example

Source: https://context7.com/zephir-lang/zephir/llms.txt

Illustrates the implementation of interfaces and abstract classes in Zephir. It defines a `RepositoryInterface`, an `AbstractRepository` class, and a concrete `UserRepository` class that extends the abstract class.

```zep
namespace MyExtension;

interface RepositoryInterface
{
    public function find(int id) -> var;
    public function findAll() -> array;
    public function save(var entity) -> bool;
    public function delete(int id) -> bool;
}

abstract class AbstractRepository implements RepositoryInterface
{
    protected connection;

    public function __construct(var connection)
    {
        let this->connection = connection;
    }

    abstract public function getTableName() -> string;

    public function findAll() -> array
    {
        return this->connection->query(
            "SELECT * FROM " . this->getTableName()
        );
    }
}

class UserRepository extends AbstractRepository
{
    public function getTableName() -> string
    {
        return "users";
    }

    public function find(int id) -> var
    {
        return this->connection->query(
            "SELECT * FROM users WHERE id = ?",
            [id]
        );
    }

    public function save(var entity) -> bool
    {
        // Implementation
        return true;
    }

    public function delete(int id) -> bool
    {
        // Implementation
        return true;
    }
}
```

--------------------------------

### Setting PHP Developer Pack Environment Variable

Source: https://github.com/zephir-lang/zephir/blob/development/WINDOWS.md

Command to set the PHP_DEV_PACK environment variable, indicating the path to the extracted PHP Developer Pack. This is necessary for certain build configurations.

```cmd
setx php_devpack "c:\path-to-extracted-devpack"
```

--------------------------------

### Initialize Zephir Extension Project (Bash)

Source: https://context7.com/zephir-lang/zephir/llms.txt

Initializes a new Zephir extension project, creating the necessary directory structure and configuration files. The command takes the desired extension name as an argument.

```bash
# Initialize a new extension named "myextension"
zephir init myextension

# This creates:
# myextension/
# ⌂ ├── config.json
# ⌂ ├── ext/
# ⌂ ⌂ └── kernel/
# ⌂ └── myextension/

```

--------------------------------

### Basic Class Definition (Zephir)

Source: https://context7.com/zephir-lang/zephir/llms.txt

Demonstrates the basic syntax for defining a class in Zephir, including namespaces, class properties, constructors, and methods with static typing.

```zep
namespace MyExtension;

class Calculator
{
    protected value = 0;

    public function __construct(int initialValue = 0)
    {
        let this->value = initialValue;
    }

    public function add(int number) -> int
    {
        let this->value += number;
        return this->value;
    }

    public function getValue() -> int
    {
        return this->value;
    }
}
```

--------------------------------

### Closures and Arrow Functions (Zephir)

Source: https://context7.com/zephir-lang/zephir/llms.txt

Shows how to define and use closures and arrow functions in Zephir. Covers simple closures, closures with variable capture using `use`, and concise arrow function syntax.

```zep
namespace MyExtension;

class ClosureExamples
{
    public function simpleClosure()
    {
        return function(var param) {
            return param * 2;
        };
    }

    public function closureWithUse()
    {
        var multiplier = 10;

        return function(var value) use (multiplier) {
            return value * multiplier;
        };
    }

    public function arrowFunction()
    {
        return x => x + 100;
    }

    public function complexArrow()
    {
        return x => (x + 100) * 2;
    }

    public function arrayMap(array! items)
    {
        var callback;

        let callback = function(item) {
            return item * 2;
        };

        return array_map(callback, items);
    }
}
```

--------------------------------

### Generate HTML API Documentation (Bash)

Source: https://context7.com/zephir-lang/zephir/llms.txt

Generates HTML documentation for the Zephir extension's classes. Allows specifying an output path and a custom theme.

```bash
# Generate API documentation
zephir api

# Specify output path
zephir api --output=docs/api

# Use custom theme
zephir api --path=/path/to/theme

```

--------------------------------

### Run Zephir Tests in Parallel with Prove (Shell)

Source: https://github.com/zephir-lang/zephir/blob/development/tests/sharness/README.md

Demonstrates how to run Zephir tests in parallel using the 'prove' TAP harness. The '--jobs' option specifies the number of parallel jobs. The '--state' option can be used to re-run only failed tests.

```shell
$ prove --jobs 15 ./t[0-9]*.sh
```

```shell
# Repeat until no more failures
$ prove -j 15 --state=failed,save ./t[0-9]*.sh
```

--------------------------------

### Control Flow and Loops (Zephir)

Source: https://context7.com/zephir-lang/zephir/llms.txt

Demonstrates common control flow structures in Zephir, including for loops (with `range`), iterating over arrays, while loops, switch statements, and basic variable declarations.

```zep
namespace MyExtension;

class FlowControl
{
    public function factorial(int n) -> int
    {
        long result = 1, i;

        for i in range(2, n) {
            let result *= i;
        }

        return result;
    }

    public function sumArray(array! numbers) -> int
    {
        int total = 0;
        var number;

        for number in numbers {
            let total += number;
        }

        return total;
    }

    public function iterateWithKeys(array! data) -> array
    {
        var key, value;
        array result = [];

        for key, value in data {
            let result[key] = value . "_processed";
        }

        return result;
    }

    public function whileExample(int max) -> int
    {
        int i = 0, sum = 0;

        while i < max {
            let sum += i;
            let i++;
        }

        return sum;
    }

    public function switchExample(string type) -> string
    {
        switch type {
            case "a":
                return "Type A";
            case "b":
                return "Type B";
            default:
                return "Unknown";
        }
    }
}
```

--------------------------------

### Run a Single Zephir Test (Bash)

Source: https://github.com/zephir-lang/zephir/blob/development/tests/sharness/README.md

Shows how to execute a specific test script by calling it directly as a shell script. This is useful for isolating and testing individual components or functionalities.

```bash
$ ./t0001-compile.sh
```

--------------------------------

### Basic Zephir Extension Configuration (JSON)

Source: https://context7.com/zephir-lang/zephir/llms.txt

Defines fundamental extension metadata, including namespace, name, description, author, version, and verbose output setting. It also specifies required extensions and configuration for stubs and API documentation.

```json
{
  "namespace": "myextension",
  "name": "My Extension",
  "description": "A high-performance PHP extension",
  "author": "Developer Name",
  "version": "1.0.0",
  "verbose": false,
  "requires": {
    "extensions": ["PDO", "json"]
  },
  "stubs": {
    "path": "ide/%version%/%namespace%/",
    "stubs-run-after-generate": false,
    "banner": "/* Auto-generated stub file */"
  },
  "api": {
    "path": "doc/%version%",
    "theme": {
      "name": "zephir",
      "options": {
        "github": "https://github.com/user/repo",
        "main_color": "#3E6496"
      }
    }
  }
}

```

--------------------------------

### Using Compiled Zephir Extension Classes in PHP

Source: https://context7.com/zephir-lang/zephir/llms.txt

Demonstrates how to use classes compiled with Zephir within a PHP environment. This includes basic class instantiation, method calls, working with typed parameters, closures, arrow functions, and static methods. Ensure the extension is enabled in your php.ini configuration.

```php
<?php
// Enable the extension in php.ini: extension=myextension.so

// Use classes from the compiled extension
use MyExtension\Calculator;
use MyExtension\TypedParams;
use MyExtension\ClosureExamples;

// Basic class usage
$calc = new Calculator(10);
$calc->add(5);
echo $calc->getValue(); // Output: 15

// Typed parameters with strict types
$params = new TypedParams();
$age = $params->setStrictAge(25);
$name = $params->setStrictName("John");

// Closures from the extension
$closures = new ClosureExamples();
$multiply = $closures->closureWithUse();
echo $multiply(5); // Output: 50

// Arrow functions
$addHundred = $closures->arrowFunction();
echo $addHundred(50); // Output: 150

// Static methods
use MyExtension\StaticExample;
$instance = StaticExample::getInstance();
StaticExample::setConfig('debug', true);
echo StaticExample::getInstanceCount(); // Output: 1

```

--------------------------------

### Debug a Single Zephir Test (Bash)

Source: https://github.com/zephir-lang/zephir/blob/development/tests/sharness/README.md

Illustrates how to run a single test script with debugging options enabled. The '-v' flag provides verbose output, while the '-i' flag halts execution immediately upon encountering a test failure.

```bash
$ ./t0001-compile.sh -v -i
```

--------------------------------

### Type Declarations and Strict Types (Zephir)

Source: https://context7.com/zephir-lang/zephir/llms.txt

Illustrates Zephir's support for various type hints, including standard types, strict types (using '!'), default parameter values, and object/class type hints. Strict types enforce type checking at runtime.

```zep
namespace MyExtension;

class TypedParams
{
    // Standard type hints (auto-cast from PHP)
    public function setAge(int age) -> int
    {
        return age;
    }

    public function setName(string name) -> string
    {
        return name;
    }

    public function setEnabled(boolean enabled) -> bool
    {
        return enabled;
    }

    public function setItems(array items) -> array
    {
        return items;
    }

    // Strict type hints (throws TypeError on mismatch)
    public function setStrictAge(int! age) -> int
    {
        return age;
    }

    public function setStrictName(string! name) -> string
    {
        return name;
    }

    // Default parameter values
    public function setAgeWithDefault(int age = 25) -> int
    {
        return age;
    }

    // Object type hints
    public function setObject(object obj) -> object
    {
        return obj;
    }

    // Class type hints
    public function setUser(<User> user) -> <User>
    {
        return user;
    }
}
```

--------------------------------

### Run All Zephir Tests (Shell)

Source: https://github.com/zephir-lang/zephir/blob/development/tests/sharness/README.md

Executes all tests in the current directory using the 'make' command. The TEST_VERBOSE environment variable can be set to 1 for detailed output during the test run. Zephir-specific environment flags, like ZEPHIR_DEBUG, can also be applied.

```shell
$ TEST_VERBOSE=1 make
```

```shell
$ ZEPHIR_DEBUG=1 TEST_VERBOSE=1 make
```

--------------------------------

### Generate C Code from Zephir Sources (Bash)

Source: https://context7.com/zephir-lang/zephir/llms.txt

Compiles Zephir source files (.zep) into C code without performing a full extension build. Supports verbose output, specific optimization flags, and disabling warnings.

```bash
# Generate C code from all .zep files
zephir generate

# With verbose output
zephir generate --verbose

# Enable specific optimizations
zephir generate -fstatic-type-inference -fconstant-folding

# Disable specific warnings
zephir generate -Wunused-variable

```

--------------------------------

### Generate IDE Stubs for Zephir Extension (Bash)

Source: https://context7.com/zephir-lang/zephir/llms.txt

Generates PHP stub files from Zephir code to provide IDE autocompletion support. The output path is configured in `config.json`.

```bash
# Generate IDE stubs
zephir stubs

# Stubs are placed in the path configured in config.json
# Default: ide/%version%/%namespace%/

```

--------------------------------

### Configure Extension Globals (JSON)

Source: https://context7.com/zephir-lang/zephir/llms.txt

Defines PHP INI settings that can be exposed by a Zephir extension. This JSON structure specifies global settings, their types, default values, and INI entry configurations.

```json
{
  "globals": {
    "my_setting": {
      "type": "bool",
      "default": true,
      "ini-entry": {
        "name": "myextension.my_setting",
        "scope": "PHP_INI_ALL"
      }
    },
    "cache_level": {
      "type": "int",
      "default": 3
    },
    "db.connection_timeout": {
      "type": "double",
      "default": 30.0
    }
  }
}
```

--------------------------------

### Compile Zephir Extension (Bash)

Source: https://context7.com/zephir-lang/zephir/llms.txt

Compiles the generated C code into a loadable PHP extension. Supports development mode, parallel compilation using the `-j` flag, and production mode.

```bash
# Compile the extension
zephir compile

# Compile in development mode (with debug symbols)
zephir compile --dev

# Compile with multiple jobs for faster builds
zephir compile -j 4

# Production mode compilation
zephir compile --no-dev

```

--------------------------------

### Zephir Compiler Warnings Configuration (JSON)

Source: https://context7.com/zephir-lang/zephir/llms.txt

Configures which compiler warnings are enabled or disabled for the Zephir build process. Boolean values indicate the status of each warning type.

```json
{
  "warnings": {
    "unused-variable": true,
    "unused-variable-external": false,
    "possible-wrong-parameter": true,
    "nonexistent-function": true,
    "nonexistent-class": true,
    "non-valid-isset": true,
    "invalid-return-type": true,
    "unreachable-code": true,
    "conditional-initialization": true
  }
}

```

--------------------------------

### Clean Zephir Build Artifacts (Bash)

Source: https://context7.com/zephir-lang/zephir/llms.txt

Removes compiled object files and other build artifacts. `fullclean` also removes phpize artifacts.

```bash
# Clean object files
zephir clean

# Full clean including phpize artifacts
zephir fullclean

```

--------------------------------

### Zephir Compiler Optimizations Configuration (JSON)

Source: https://context7.com/zephir-lang/zephir/llms.txt

Enables or disables specific compiler optimizations for Zephir. Boolean values determine whether an optimization is active during compilation.

```json
{
  "optimizations": {
    "static-type-inference": true,
    "static-type-inference-second-pass": true,
    "local-context-pass": true,
    "constant-folding": true,
    "static-constant-class-folding": true,
    "call-gatherer-pass": true,
    "check-invalid-reads": false,
    "internal-call-transformation": false
  }
}

```
Tokens:
Raw