Getting Started

Get up and running with Rowcast in under 5 minutes.

Table of contents

Installation

Install Rowcast via Composer:

composer require ascetic-soft/rowcast

Requirements:

  • PHP >= 8.4
  • PDO extension

Your First DTO

Step 1: Define a DTO class 

// src/User.php
class User
{
    public int $id;
    public string $name;
    public string $email;
}

No base class, no interfaces, no annotations — just a plain PHP class with typed properties.

Step 2: Create a connection 

use AsceticSoft\Rowcast\Connection;

$connection = Connection::create(
    dsn: 'mysql:host=localhost;dbname=app',
    username: 'root',
    password: 'secret',
);

Step 3: Create a DataMapper and perform CRUD 

use AsceticSoft\Rowcast\DataMapper;

$mapper = new DataMapper($connection);

// Insert
$user = new User();
$user->name = 'Alice';
$user->email = 'alice@example.com';
$id = $mapper->insert('users', $user);

// Find
$user = $mapper->findOne(User::class, ['id' => 1]);

// Update
$user->name = 'Alice Updated';
$mapper->update('users', $user, ['id' => $user->id]);

// Delete
$mapper->delete('users', ['id' => $user->id]);

How Auto Mode Works

When you pass a class-string (e.g. User::class) to read methods, Rowcast:

  1. Derives the table name from the class name (User → users, UserProfile → user_profiles)
  2. Executes the SQL query against the derived table
  3. Maps each column to a property using SnakeCaseToCamelCaseConverter (created_at → createdAt)
  4. Casts values to the declared PHP types (string → int, "2025-01-01" → DateTimeImmutable, etc.)
  5. Returns fully hydrated DTO objects

All of this happens automatically — no configuration required.

Uninitialized properties (e.g. auto-increment id) are automatically skipped during insert(). This means you don’t need to set a default value for your primary key.

Working with Enums

Rowcast supports BackedEnum types out of the box:

enum Status: string
{
    case Active = 'active';
    case Inactive = 'inactive';
}

class UserDto
{
    public int $id;
    public string $name;
    public Status $status;
}

$dto = new UserDto();
$dto->name = 'Alice';
$dto->status = Status::Active;

$mapper->insert('users', $dto);
// Stored as: status = 'active'

$user = $mapper->findOne(UserDto::class, ['id' => 1]);
// $user->status === Status::Active

Working with DateTime

DateTime, DateTimeImmutable, and DateTimeInterface properties are automatically handled:

class Post
{
    public int $id;
    public string $title;
    public DateTimeImmutable $createdAt;
}

$post = new Post();
$post->title = 'Hello World';
$post->createdAt = new DateTimeImmutable();

$mapper->insert('posts', $post);
// Stored as: created_at = '2025-06-15 10:30:00'

$found = $mapper->findOne(Post::class, ['id' => 1]);
// $found->createdAt instanceof DateTimeImmutable

What’s Next?

  • Connection — PDO wrapper, raw queries, transactions, and savepoints
  • DataMapper — Full CRUD operations reference
  • Mapping — Auto mode vs explicit ResultSetMapping
  • Type Casting — All built-in type casters and custom casters
  • Query Builder — Fluent SQL query builder
  • API Reference — Complete class and method reference