Marten Web Framework

Marten follows a 'batteries included' philosophy, providing several essential web application features out of the box without requiring immediate external configuration. These built-in features include:

• ORM: Object-Relational Mapping for database interactions.
• Migrations: Tools for managing database schema changes.
• Translations: Internationalization (i18n) support.
• Templating Engine: For rendering views.
• Sessions: Managing user sessions.
• Emailing: Support for sending emails.
• Authentication: Handling user identity and access.

The Marten documentation is organized into several types of content to help you find information based on your needs:

• Topic-specific guides: Explain core framework concepts such as models, handlers, and templates.
• Reference pages: Provide a curated technical reference of the framework's public APIs.
• How-to guides: Offer solutions for common tasks like deployment and application development.
• API Reference: An automatically-generated API reference is available for deep dives into Marten's internals.

A standard Marten project generated via marten new includes the following structure:

Callbacks are methods triggered at specific stages of a handler's lifecycle. They allow you to intercept requests, modify responses, or manipulate data before or after standard operations like #dispatch, #render, or schema validation.

To use a callback, you must explicitly register it in your handler class using a callback macro (e.g., before_dispatch :method_name) and provide a symbol representing the method to be executed.

Key Behavior: Bypassing Logic If a callback returns a Marten::HTTP::Response object, that response is used immediately, and subsequent standard handler logic (like the #dispatch method or following callbacks) is bypassed.

class MyHandler < Marten::Handler
  before_dispatch :my_callback_method

  private def my_callback_method
    # logic here
  end
end

Marten models allow you to define validation rules directly within field definitions. Rules are inherited from the field type and the options provided. For example, using blank: false ensures a field is not empty, and max_size: N restricts the length of string fields. These rules are database-agnostic and run automatically before persistence.

Common field-based validation triggers include:

• Field Type: e.g., a uuid field validates that the value is a valid UUID.
• Field Options: e.g., blank: false or max_size: 128.

class User < Marten::Model
  field :id, :big_int, primary_key: true, auto: true
  field :name, :string, max_size: 128, blank: false
end

Marten uses the MARTEN_ENV environment variable to determine the current running environment. If MARTEN_ENV is not set, the application defaults to development.

The value of MARTEN_ENV must match the argument passed to Marten.configure.

When using the new management command, Marten automatically creates the following environment files:

• config/settings/development.cr
• config/settings/test.cr
• config/settings/production.cr

Emailing backends determine how emails are delivered (e.g., printing to stdout in development or using an SMTP server in production).

• Global Configuration: Controlled by the emailing.backend setting.
• Per-Email Override: You can override the backend for a specific email class using the #backend class method.

class WelcomeEmail < Marten::Email
  # ... properties ...
  backend Marten::Emailing::Backend::Development.new(print_emails: true)

  def initialize(@user : User)
  end
end

class WelcomeEmail < Marten::Email
  from "no-reply@martenframework.com"
  to @user.email
  subject "Hello!"
  template_name "emails/welcome_email.html"

  backend Marten::Emailing::Backend::Development.new(print_emails: true)

  def initialize(@user : User)
  end
end

When you access a :file or :image field on a model, Marten returns an instance of Marten::DB::Field::File::File. These objects represent the association between the model and the file.

File objects have two key states:

• Attached: The object has an associated file set (#attached? returns true).
• Committed: The file has been successfully persisted to the underlying storage (#committed? returns true).

Note that file objects are always associated with a model record (whether persisted or not) and are only available via :file model fields.

attachment = Attachment.last!
attachment.uploaded_file.attached?  # => true
attachment.uploaded_file.committed? # => true

Marten provides built-in CSRF protection that is automatically enabled for handlers. It works by verifying a token for all 'unsafe' HTTP requests (methods other than GET, HEAD, OPTIONS, or TRACE).

How it works:

1. A token is stored in client cookies.
2. The client must provide this token in the request data or via a specific header.
3. Marten rejects the request if the tokens are invalid or if the cookie-based token does not match the one provided in the request.

Configuration: Control the CSRF protection mechanism using dedicated settings found in the framework settings documentation.