DEV Community: Anton Samoylov

PHORM: a Dart/Flutter ORM that loads your whole object graph in one SQL query

Anton Samoylov — Tue, 30 Jun 2026 13:19:06 +0000

PHORM: the Flutter ORM that loads your whole object graph in one query

If you have ever built a Flutter app with a local database, you know the three taxes you pay:

Stringly-typed everything. row['user_name'] as String? scattered across the codebase, errors discovered at runtime.
Boilerplate. Hand-written DAOs, toJson/fromJson, mappers, query helpers — for every single model.
The N+1 problem. Load 50 posts, then fire 50 more queries to load each author. Your "fast local DB" suddenly feels slow.

PHORM (Predictable Harmonious ORM) is a lightweight, type-safe, driver-agnostic ORM for Dart and Flutter built specifically to remove all three. Let me show you the parts that actually change how you write data code.

1. You write a plain class. PHORM writes the rest.

You annotate a normal Dart class:

@Schema(tableName: 'users')
class User extends Model with _$PhormUserMixin {
  @ID(autoIncrement: true)
  final int id;

  @Column(unique: true)
  final String email;

  @Column()
  final String name;

  @Column()
  final int age;

  User({required this.id, required this.email, required this.name, required this.age});

  factory User.fromJson(Map<String, dynamic> json) => _$PhormUserFromJson(json);
}

Run build_runner, and PHORM generates:

the CREATE TABLE / index / foreign-key SQL,
toJson / fromJson / copyWith / toString,
type-safe column descriptors (Users.age, Users.email, …),
and a full Active-Record-style service class (Users).

No DAO. No mapper. No Map<String, dynamic> in your business logic.

💡 There's even a VS Code extension that converts a plain Dart class into a fully annotated PHORM model in one click.

2. A data API that reads like a sentence

Because the service is generated per-model, your queries are fully typed and discoverable through autocomplete:

// Create
await Users.insert(user);

// Read by primary key
final user = await Users.readOne(1);

// Fluent, type-safe queries
final adults = await Users
    .where(Users.age.gt(18))
    .where(Users.name.like('%John%'))
    .orderBy(Users.name)
    .get();

// Pagination with a total count, in one call
final page = await Users.readAllWithCount(limit: 20, offset: 0);

Users.age.gt(18) is not a string — it's a typed PhormColumn<int>. Pass the wrong type and it won't compile. Every value is parameterized, so you get SQL-injection protection for free.

3. The killer feature: one query for the entire object graph

This is where PHORM earns its name. Say a User has many Posts, and each Post belongs to a Category. The naive ORM approach fires a cascade of queries (the N+1 problem). PHORM instead compiles the whole tree into a single SQL statement using the database's native JSON functions (SQLite's json_group_array, PostgreSQL's jsonb_agg):

final users = await Users
    .where(Users.age.gt(18))
    .include([
      Includable.model<Post>(
        include: [Includable.model<Category>()],
      ),
    ])
    .get();

// users.first.posts.first.category.name  —  already loaded, fully typed.

One round trip. No N+1. No manual joins. No stitching results together in Dart. On a list screen that shows nested relationships, this is the difference between janky and instant.

You can still filter by a related table's column — PHORM adds the LEFT JOIN for you automatically.

4. Driver-agnostic by design

PHORM separates query building and relationship mapping from database-specific SQL grammar via a pluggable Dialect system. The same models and the same generated API are meant to run across multiple SQL backends:

SQLite today (phorm_sqlite), including a Flutter Web (WASM + IndexedDB) backend with zero code changes.
PostgreSQL and MySQL dialects are scaffolded for the future.

Your application code doesn't care which one it talks to.

5. The everyday essentials, built in

Migrations — versioned, idempotent, with a fluent migrate() builder (addColumn, renameColumn, createIndex, custom, …).
Soft deletes — opt-in paranoid mode with delete / restore.
Timestamps — automatic createdAt / updatedAt.
Batch & transactions — atomic insertBatch / updateBatch and real transactions with a shared executor.
Validators — @Column(validators: [...]) generates both SQL CHECK constraints and Dart-side validate().

And when you don't want the large generated service for a given model, the new @Schema(generateFullService: false) keeps the output lean.

6. Reactive by default — perfect for Flutter

This is the part Flutter developers tend to love. Every model service exposes reactive streams that re-emit whenever the underlying data changes, so your widgets can be driven straight from the database — no manual refresh, no event bus, no "pull to reload after insert".

// Watch a single row by id (with relationships if you want)
Stream<User?> user$ = Users.watchOne(1);

// Watch a filtered, sorted, limited list
Stream<List<User>> activeAdults$ = Users.watchAll(
  where: WhereBuilder().gt(Users.age, 18),
  sort: SortBuilder().asc(Users.name),
  limit: 50,
  include: [Includable.model<Post>()], // nested data, still one query
);

Drop either stream into a StreamBuilder and the UI just stays in sync:

StreamBuilder<List<User>>(
  stream: Users.watchAll(
    where: WhereBuilder().eq(Users.status, 'active'),
    sort: SortBuilder().desc(Users.createdAt),
  ),
  builder: (context, snapshot) {
    final users = snapshot.data ?? const [];
    return ListView.builder(
      itemCount: users.length,
      itemBuilder: (_, i) => ListTile(
        title: Text(users[i].name),
        subtitle: Text(users[i].email),
      ),
    );
  },
);

Now call Users.insert(...), Users.update(...) or Users.delete(...) from anywhere in the app — the list rebuilds automatically. Because the same JSON-aggregation engine powers the streams, watching a list with nested relationships still costs one query per emission. It pairs naturally with StreamBuilder, StreamProvider, BlocProvider, or any state-management approach you already use.

Getting started

dependencies:
  phorm_sqlite: ^1.2.0 # SQLite driver — re-exports the phorm core

dev_dependencies:
  phorm_generator: ^1.2.0
  build_runner: ^2.4.0

dart run build_runner build --delete-conflicting-outputs

That's it — annotate your models, generate, and start querying.

Why I think it's worth a look

Most local-DB solutions force a trade-off: either raw and fast but stringly-typed, or "nice" but slow once relationships show up. PHORM's bet is that you shouldn't have to choose — type safety, an ergonomic Active-Record API, and single-query performance can coexist, with codegen doing the heavy lifting.

If you build Flutter apps with non-trivial local data, give it a try:

pub.dev: phorm_sqlite
GitHub: interdev7/phorm
VS Code extension: PHORM Code Generator

If you try it, I'd love to hear what your data layer looked like before — and after. ⚡

🚀 I built a CLI to send Firebase push notifications in one command

Anton Samoylov — Fri, 27 Mar 2026 10:51:21 +0000

Sending Firebase push notifications should be simple.

But in reality, it usually means:

setting up Firebase Admin SDK
writing boilerplate code
managing credentials
rebuilding scripts again and again

So I built a tool to fix that.

⚡ Meet FCM CLI

A lightweight CLI to send Firebase Cloud Messaging (FCM) notifications directly from your terminal, CI/CD pipelines, or backend scripts.

fcm -t TOKEN -n '{"title":"Hi","body":"Hello"}'

That’s it.

💡 Why I built it

As a developer, I kept running into the same problems:

I just wanted to test a push notification quickly
I didn’t want to write a full Firebase script
CI/CD pipelines needed a simple way to send notifications
Existing tools felt heavy or overcomplicated

So I created something:

simple
fast
developer-friendly

🔥 Features

🚀 Send notifications in seconds
⚡ Works in CI/CD pipelines
📦 Single binary (no dependencies)
🧩 YAML config + profiles
🔐 .env support
📄 Batch sending (--tokens-file)
🎯 Supports token, topic, and conditions
🔁 Retry with exponential backoff
🤖 Structured JSON output for automation
🌐 Works from any language through CLI execution

🧩 YAML config (game changer)

Instead of writing scripts, you can define everything in fcm.yaml:

notification:
  title: Hello
  body: World

profiles:
  prod:
    topic: production
    notification:
      title: Deploy
      body: New version released

Run:

fcm --config fcm.yaml --profile prod

⚡ Batch sending

fcm --tokens-file tokens.txt -n '{"title":"Hello","body":"Batch"}'

🧠 Use cases

Testing push notifications
CI/CD automation
Backend scripts
Debugging Firebase messaging
Bulk notifications

🎯 Goal

Make push notifications:

simpler
faster
less painful

📦 Installation

curl -fsSL https://raw.githubusercontent.com/interdev7/fcm-cli/main/install.sh | bash

or:

brew tap interdev7/fcm
brew install fcm

❤️ Open Source

The project is fully open-source.

If it saves you time or helps your workflow — consider supporting it.

🔗 GitHub

👉 https://github.com/interdev7/fcm-cli

💬 Feedback

Would love to hear what you think 👇

Flutter Anti-Pattern: How setState() Turns Your App Into a Slideshow

Anton Samoylov — Thu, 26 Mar 2026 08:21:06 +0000

The Problem: Many Flutter developers overuse setState(), calling it even when variable changes don't affect the UI. Every unnecessary setState() is a potential drop from 60 FPS to 59 FPS in complex interfaces.

Chapter 1: When setState Is Actually Unnecessary

Let’s examine a classic example found in 80% of applications: data entry forms. Developers often write:

class MyForm extends StatefulWidget {
  @override
  _MyFormState createState() => _MyFormState();
}

class _MyFormState extends State<MyForm> {
  String _username = '';
  String _password = '';

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        TextField(
          onChanged: (value) {
            setState(() {          // ❌ UNNECESSARY!
              _username = value;   // This variable is NOT used in UI
            });
          },
        ),
        TextField(
          onChanged: (value) {
            setState(() {          // ❌ UNNECESSARY!
              _password = value;   // This variable is also NOT in UI
            });
          },
        ),
        ElevatedButton(
          onPressed: () {
            // Send data to server
            _sendToServer(_username, _password);
          },
          child: Text('Submit'),
        ),
      ],
    );
  }

  void _sendToServer(String user, String pass) {
    // Send data...
  }
}

What’s wrong here? Every character typed triggers a complete widget rebuild, even though nothing visually changes! The user sees just the cursor blinking, but under the hood Flutter rebuilds the entire widget tree.
The right approach: If data is only needed for logic or server submission — store it without UI binding:

class _MyFormState extends State<MyForm> {
  // These variables are NOT used in build()
  final TextEditingController _usernameController = TextEditingController();
  final TextEditingController _passwordController = TextEditingController();

  @override
  void initState() {
    super.initState();
    // You can add listeners for additional logic
    _usernameController.addListener(() {
      print('Username changed: ${_usernameController.text}');
      // You can do validation, debounce, etc. here
    });
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        TextField(controller: _usernameController),
        TextField(controller: _passwordController),
        ElevatedButton(
          onPressed: () {
            // Take data directly from controllers
            _sendToServer(
              _usernameController.text,
              _passwordController.text,
            );
          },
          child: Text('Submit'),
        ),
      ],
    );
  }
}

Key principle: If a variable isn’t displayed in build() and doesn't affect how other widgets are displayed — it's not part of UI state and doesn't need setState().

Chapter 2: When setState IS Needed — Do It Precisely

There are cases where a variable truly affects UI, but that doesn’t mean you need to rebuild everything. Let’s look at smarter approaches.

❌ Typical case of excessive setState:

class ProductCard extends StatefulWidget {
  @override
  _ProductCardState createState() => _ProductCardState();
}

class _ProductCardState extends State<ProductCard> {
  bool _isFavorite = false;
  bool _isInCart = false;

  @override
  Widget build(BuildContext context) {
    return Card(
      child: Column(
        children: [
          Image.network('...'),
          Text('Product Name'),
          Row(
            children: [
              IconButton(
                icon: Icon(
                  _isFavorite ? Icons.favorite : Icons.favorite_border,
                  color: _isFavorite ? Colors.red : Colors.grey,
                ),
                onPressed: () {
                  setState(() {          // ❌ Rebuilds the ENTIRE Card!
                    _isFavorite = !_isFavorite;
                  });
                },
              ),
              IconButton(
                icon: Icon(
                  _isInCart ? Icons.shopping_cart : Icons.add_shopping_cart,
                  color: _isInCart ? Colors.green : Colors.grey,
                ),
                onPressed: () {
                  setState(() {          // ❌ Rebuilds the ENTIRE Card again!
                    _isInCart = !_isInCart;
                  });
                },
              ),
            ],
          ),
        ],
      ),
    );
  }
}

Problem: We’re changing only the button color and icon, but rebuilding the entire product card with image, text, and all other elements!

✅ Solution 1: ValueNotifier for precise updates

class ProductCard extends StatelessWidget {
  final ValueNotifier<bool> _isFavorite = ValueNotifier<bool>(false);
  final ValueNotifier<bool> _isInCart = ValueNotifier<bool>(false);

  @override
  Widget build(BuildContext context) {
    return Card(
      child: Column(
        children: [
          Image.network('...'),  // ❌ This part WON'T rebuild
          Text('Product Name'),   // ❌ This either
          Row(
            children: [
              // ✅ Only this icon will rebuild
              ValueListenableBuilder<bool>(
                valueListenable: _isFavorite,
                builder: (context, isFavorite, child) {
                  return IconButton(
                    icon: Icon(
                      isFavorite ? Icons.favorite : Icons.favorite_border,
                      color: isFavorite ? Colors.red : Colors.grey,
                    ),
                    onPressed: () {
                      _isFavorite.value = !isFavorite; // Just change value
                    },
                  );
                },
              ),
              // ✅ And this icon too
              ValueListenableBuilder<bool>(
                valueListenable: _isInCart,
                builder: (context, isInCart, child) {
                  return IconButton(
                    icon: Icon(
                      isInCart ? Icons.shopping_cart : Icons.add_shopping_cart,
                      color: isInCart ? Colors.green : Colors.grey,
                    ),
                    onPressed: () {
                      _isInCart.value = !isInCart;
                    },
                  );
                },
              ),
            ],
          ),
        ],
      ),
    );
  }
}

What changed:

Product image and text no longer rebuild on click
Only the specific icon updates
Code became more declarative

✅ Solution 2: Extract changing part into separate StatefulWidget

class FavoriteButton extends StatefulWidget {
  @override
  _FavoriteButtonState createState() => _FavoriteButtonState();
}

class _FavoriteButtonState extends State<FavoriteButton> {
  bool _isFavorite = false;

  @override
  Widget build(BuildContext context) {
    return IconButton(
      icon: Icon(
        _isFavorite ? Icons.favorite : Icons.favorite_border,
        color: _isFavorite ? Colors.red : Colors.grey,
      ),
      onPressed: () {
        setState(() {
          _isFavorite = !_isFavorite; // Only button rebuilds
        });
      },
    );
  }
}

// Use in main widget
class ProductCard extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Card(
      child: Column(
        children: [
          Image.network('...'),
          Text('Product Name'),
          Row(
            children: [
              FavoriteButton(),      // Isolated state
              CartButton(),          // Another isolated state
            ],
          ),
        ],
      ),
    );
  }
}

Chapter 3: Checklist and Practical Rules

The 5-Second Rule
Before writing setState(), ask yourself:

“If I change this variable, will the user see visual changes within the next 5 seconds?”

If no (data goes to server, saves to DB, used for calculations) — you don’t need setState().

Simple Test for Your Code
Try temporarily commenting out setState():

onChanged: (value) {
  // setState(() {          // Commented out
    _someValue = value;    // Data still saves!
  // });
}

If UI works correctly — setState was unnecessary.

Strategy Guide:

Variable doesn’t affect UI → simple assignment

_apiToken = 'new_token';  // For sending requests
_userData = json;         // For processing
_cache = data;            // For storage

2 Affects one small element → ValueNotifier + ValueListenableBuilder
3 Affects several related widgets → extract to separate StatefulWidget
4 Affects entire screen/widget → setState() (use rarely and deliberately)

Typical Scenarios Without setState:

// Logging and analytics
onPressed: () {
  _clickCounter++;        // Just a variable
  _logEvent('button_click');
}

// Timers for logic
Timer.periodic(Duration(seconds: 30), (timer) {
  _lastUpdate = DateTime.now();  // For internal logic
  _checkForUpdates();
});

// Data caching
Future<void> _loadData() async {
  final data = await api.fetchData();
  _cachedData = data;     // Save, but don't rebuild
  _processData(data);
}

Conclusion: Ultimate Cheatsheet

When NOT to use setState:
• Data sent to server
• Saved to database/cache
• Used for logic/calculations
• For analytics/logging
• Temporary processing variables
When setState needed, but precisely:
• Button color/icon changes → ValueNotifier
• Text field updates → separate widget
• UI element state toggles → isolated state
When setState is justified:
• Large portion of screen changes
• Complex animation updates
• Entire list/table rebuilds

Remember: Flutter is not React. You don’t need to update state on every change. Separate UI state from business logic, and your app will run smoothly even on low-end devices.

Every unnecessary setState() is a step from "works fine" to "slideshow mode." Be intentional about state management!