hanami 2.3.2 → 3.0.0

data/lib/hanami/extensions/view/context.rb

@@ -25,6 +25,8 @@ module Hanami
             end
 
             views_namespace.const_set(:Context, Class.new(context_superclass(slice)).tap { |klass|
+              # Call configure_for_slice explicitly, since this is an anonymous class at this point,
+              # so the slice cannot be inferred from its name.
               klass.configure_for_slice(slice)
             })
           end
@@ -40,8 +42,8 @@ module Hanami
               slice.inflector.constantize(
                 slice.inflector.camelize("#{slice.app.slice_name.name}/views/context")
               )
-            rescue NameError => e
-              raise e unless %i[Views Context].include?(e.name)
+            rescue NameError => exception
+              raise exception unless %i[Views Context].include?(exception.name)
 
               Hanami::View::Context
             end
@@ -95,17 +97,19 @@ module Hanami
             #
             # @api private
             # @since 2.1.0
-            def initialize( # rubocop:disable Metrics/ParameterLists
+            def initialize(
               inflector: nil,
               routes: nil,
               assets: nil,
               request: nil,
+              i18n: nil,
               **args
             )
               @inflector = inflector
               @routes = routes
               @assets = assets
               @request = request
+              @i18n = i18n
 
               @content_for = {}
 
@@ -157,7 +161,9 @@ module Hanami
             # @since 2.1.0
             def request
               unless @request
-                raise Hanami::ComponentLoadError, "Request not available. Only views rendered from Hanami::Action instances have a request."
+                raise Hanami::ComponentLoadError, <<~STR
+                  Request not available. Only views rendered from Hanami::Action instances have a request.
+                STR
               end
 
               @request
@@ -190,6 +196,22 @@ module Hanami
               @routes
             end
 
+            # Returns the slice's i18n backend.
+            #
+            # @return [Hanami::Providers::I18n::Backend] the i18n backend
+            #
+            # @raise [Hanami::ComponentLoadError] if the i18n gem is not bundled
+            #
+            # @api public
+            # @since 3.0.0
+            def i18n
+              unless @i18n
+                raise Hanami::ComponentLoadError, "the i18n gem is required to access translations"
+              end
+
+              @i18n
+            end
+
             # @overload content_for(key, value = nil, &block)
             #   Stores a string or block of template markup for later use.
             #

data/lib/hanami/extensions/view/part.rb

@@ -27,6 +27,8 @@ module Hanami
             extend SliceConfiguredPart.new(slice)
 
             const_set :PartHelpers, Class.new(PartHelpers) { |klass|
+              # Call configure_for_slice explicitly, since this is an anonymous class at this point,
+              # so the slice cannot be inferred from its name.
               klass.configure_for_slice(slice)
             }
           end

data/lib/hanami/extensions/view/slice_configured_context.rb

@@ -39,15 +39,18 @@ module Hanami
         #   - the configured inflector as `inflector`
         #   - "routes" from the app container as `routes`
         #   - "assets" from the app container as `assets`
+        #   - "i18n" from the slice container as `i18n`
         def define_new
           inflector = slice.inflector
           resolve_routes = method(:resolve_routes)
           resolve_assets = method(:resolve_assets)
+          resolve_i18n = method(:resolve_i18n)
 
           define_method :new do |**kwargs|
             kwargs[:inflector] ||= inflector
             kwargs[:routes] ||= resolve_routes.()
             kwargs[:assets] ||= resolve_assets.()
+            kwargs[:i18n] ||= resolve_i18n.()
 
             super(**kwargs)
           end
@@ -60,6 +63,10 @@ module Hanami
         def resolve_assets
           slice["assets"] if slice.key?("assets")
         end
+
+        def resolve_i18n
+          slice["i18n"] if slice.key?("i18n")
+        end
       end
     end
   end

data/lib/hanami/extensions/view/slice_configured_part.rb

@@ -57,6 +57,8 @@ module Hanami
           define_method(:new) do |**args|
             return super(**args) if args.key?(:rendering)
 
+            # Call configure_for_slice explicitly, since this is an anonymous class at this point,
+            # so the slice cannot be inferred from its name.
             slice_rendering = Class.new(Hanami::View)
               .configure_for_slice(slice)
               .new

data/lib/hanami/extensions/view/slice_configured_view.rb

@@ -49,12 +49,12 @@ module Hanami
 
           begin
             slice.app.namespace.const_get(:View, false)
-          rescue NameError => e
-            raise unless e.name == :View
+          rescue NameError => exception
+            raise unless exception.name == :View
           end
         end
 
-        # rubocop:disable Metrics/AbcSize
+        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         def configure_view(view_class)
           view_class.settings.each do |setting|
             next unless slice.config.views.respond_to?(setting.name)
@@ -134,7 +134,7 @@ module Hanami
             view_class.config.scope_namespace = scope_namespace
           end
         end
-        # rubocop:enable Metrics/AbcSize
+        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
         def define_inherited
           template_name = method(:template_name)
@@ -185,8 +185,8 @@ module Hanami
               views_namespace.const_get(:Part)
             else
               views_namespace.const_set(:Part, Class.new(part_superclass).tap { |klass|
-                # Give the slice to `configure_for_slice`, since it cannot be inferred when it is
-                # called via `.inherited`, because the class is anonymous at this point
+                # Call configure_for_slice explicitly, since this is an anonymous class at this point,
+                # so the slice cannot be inferred from its name.
                 klass.configure_for_slice(slice)
               })
             end
@@ -208,8 +208,8 @@ module Hanami
               views_namespace.const_get(:Scope)
             else
               views_namespace.const_set(:Scope, Class.new(scope_superclass).tap { |klass|
-                # Give the slice to `configure_for_slice`, since it cannot be inferred when it is
-                # called via `.inherited`, since the class is anonymous at this point
+                # Call configure_for_slice explicitly, since this is an anonymous class at this point,
+                # so the slice cannot be inferred from its name.
                 klass.configure_for_slice(slice)
               })
             end

data/lib/hanami/extensions/view/standard_helpers.rb

@@ -16,6 +16,10 @@ module Hanami
         if Hanami.bundled?("hanami-assets")
           include Helpers::AssetsHelper
         end
+
+        if Hanami.bundled?("i18n")
+          include Helpers::I18nHelper
+        end
       end
     end
   end

data/lib/hanami/extensions.rb

@@ -4,7 +4,7 @@ if Hanami.bundled?("hanami-db")
   require_relative "extensions/db/repo"
 end
 
-if Hanami.bundled?("hanami-controller")
+if Hanami.bundled?("hanami-action")
   require_relative "extensions/action"
 end
 
@@ -20,6 +20,11 @@ if Hanami.bundled?("hanami-router")
   require_relative "extensions/router/errors"
 end
 
+if Hanami.bundled?("hanami-mailer")
+  require "hanami/mailer"
+  require_relative "extensions/mailer"
+end
+
 if Hanami.bundled?("dry-operation")
   require_relative "extensions/operation"
 end

data/lib/hanami/helpers/assets_helper.rb

@@ -4,8 +4,6 @@ require "uri"
 require "hanami/view"
 require_relative "../constants"
 
-# rubocop:disable Metrics/ModuleLength
-
 module Hanami
   module Helpers
     # HTML assets helpers
@@ -804,5 +802,3 @@ module Hanami
     end
   end
 end
-
-# rubocop:enable Metrics/ModuleLength

data/lib/hanami/helpers/form_helper.rb

@@ -32,7 +32,7 @@ module Hanami
 
       # CSRF Token session key
       #
-      # This name of this key is shared with the hanami and hanami-controller gems.
+      # This name of this key is shared with the hanami and hanami-action gems.
       #
       # @since 2.1.0
       # @api private

data/lib/hanami/helpers/i18n_helper.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require "cgi/escape"
+
+module Hanami
+  module Helpers
+    # View-layer translation and localization helpers.
+    #
+    # These helpers are automatically available in your view templates, part classes, and scope
+    # classes when the `i18n` gem is bundled. They provide `translate`/`t`, `translate!`/`t!`, and
+    # `localize`/`l`, sourcing the i18n backend from the view context and expanding relative
+    # (leading-dot) translation keys against the currently-rendering template name.
+    #
+    # The shared `translate`/`localize` logic lives in {Methods}, which is also included by the
+    # action-layer i18n helper ({Hanami::Extensions::Action::I18nHelper}). This module supplies
+    # the two view-specific concrete implementations of {Methods}'s abstract hooks: {#_i18n}
+    # returns the i18n backend from the view context, and {#_resolve_i18n_key} expands relative
+    # keys against the template name.
+    #
+    # @example Basic translation
+    #   <%= translate("messages.welcome") %>
+    #   # => "Welcome"
+    #
+    # @example HTML-safe translation
+    #   # en.yml
+    #   #   greeting_html: "Hello, <strong>%{name}</strong>!"
+    #   <%= translate("greeting_html", name: "<script>") %>
+    #   # => "Hello, <strong>&lt;script&gt;</strong>!" (marked HTML-safe)
+    #
+    # @example Missing translation
+    #   <%= translate("missing.key") %>
+    #   # => '<span class="translation_missing" title="...">missing.key</span>'
+    #
+    # @example Relative key lookup
+    #   # In app/templates/users/index.html.erb:
+    #   <%= translate(".title") %>
+    #   # Looks up "users.index.title"
+    #
+    #   # In app/templates/users/_form.html.erb (a partial):
+    #   <%= translate(".label") %>
+    #   # Looks up "users._form.label"
+    #
+    # @api public
+    # @since 3.0.0
+    module I18nHelper
+      # Shared `translate` / `localize` (and shorthand) helper methods used by both view-layer
+      # consumers and action-layer consumers.
+      #
+      # **This module is abstract.** Including modules must override two private hooks:
+      #
+      # - {#_i18n} — returns the i18n backend to delegate to.
+      # - {#_resolve_i18n_key} — expands relative (leading-dot) keys against the consumer's
+      #   context, and is a no-op for absolute keys.
+      #
+      # @api public
+      # @since 3.0.0
+      module Methods
+        # Matches keys whose final segment is `html` or whose final segment ends in `_html`. These
+        # translated values are treated as HTML-safe and any string interpolation values are
+        # HTML-escaped before substitution.
+        #
+        # @api private
+        HTML_SAFE_TRANSLATION_KEY = /(\b|_)html\z/
+
+        # Translates the given key using the slice's i18n backend.
+        #
+        # When the key's final segment is `html` or ends in `_html`, the result is marked HTML-safe
+        # and any string interpolation values are HTML-escaped first.
+        #
+        # When a translation is missing and neither `:default` nor `:raise` was supplied, returns a
+        # `<span class="translation_missing">` element containing the missing key, useful for
+        # spotting missing translations during development.
+        #
+        # When the key begins with a `.`, it is treated as relative to the consumer's context and
+        # expanded by {#_resolve_i18n_key}.
+        #
+        # @param key [String, Symbol] the translation key to look up
+        # @param options [Hash] translation options forwarded to the backend (`:locale`, `:scope`,
+        #   `:default`, `:count`, `:raise`, etc.), plus any interpolation values
+        #
+        # @return [String] the translated string (marked HTML-safe when hanami-view is bundled and
+        #   the key ends in `_html` or `html`)
+        #
+        # @api public
+        # @since 3.0.0
+        def translate(key, **options)
+          key = _resolve_i18n_key(key)
+
+          html_safe = _html_safe_translation_key?(key)
+
+          options = _escape_translation_options(options) if html_safe
+
+          result =
+            if options.key?(:default) || options[:raise]
+              _i18n.translate(key, **options)
+            else
+              begin
+                _i18n.translate(key, **options, raise: true)
+              rescue ::I18n::MissingTranslationData => exception
+                return _missing_translation_markup(key, exception)
+              end
+            end
+
+          html_safe ? _i18n_mark_html_safe(result.to_s) : result
+        end
+
+        # @api public
+        # @since 3.0.0
+        alias_method :t, :translate
+
+        # Translates the given key, raising an exception if the translation is missing.
+        #
+        # @param (see #translate)
+        #
+        # @return [String] the translated string (marked HTML-safe when hanami-view is bundled and
+        #   the key ends in `_html` or `html`)
+        #
+        # @raise [I18n::MissingTranslationData] if the translation is missing
+        #
+        # @api public
+        # @since 3.0.0
+        def translate!(key, **options)
+          translate(key, **options, raise: true)
+        end
+
+        # @api public
+        # @since 3.0.0
+        alias_method :t!, :translate!
+
+        # Localizes the given object (e.g. a date, time, or number) using the slice's i18n backend.
+        #
+        # @param object [Date, Time, DateTime, Numeric] the object to localize
+        # @param options [Hash] localization options forwarded to the backend (`:locale`, `:format`,
+        #   etc.)
+        #
+        # @return [String] the localized string
+        #
+        # @api public
+        # @since 3.0.0
+        def localize(object, **options)
+          _i18n.localize(object, **options)
+        end
+
+        # @api public
+        # @since 3.0.0
+        alias_method :l, :localize
+
+        private
+
+        # Returns the i18n backend the helper methods delegate to.
+        #
+        # Including modules must override this method to return an I18n backend instance.
+        #
+        # @return [Hanami::Providers::I18n::Backend]
+        def _i18n
+          raise NoMethodError, "#{self.class} must implement #_i18n to return an i18n backend"
+        end
+
+        # Resolves the given key, returning it unchanged by default.
+        #
+        # Override this hook to expand relative (leading-dot) keys against a context.
+        #
+        # @param key [String, Symbol]
+        #
+        # @return [String, Symbol] the resolved key
+        def _resolve_i18n_key(key)
+          key
+        end
+
+        def _html_safe_translation_key?(key)
+          HTML_SAFE_TRANSLATION_KEY.match?(key.to_s)
+        end
+
+        def _escape_translation_options(options)
+          options.each_with_object({}) do |(key, value), result|
+            result[key] =
+              if ::I18n::RESERVED_KEYS.include?(key) || !value.is_a?(String) || _i18n_html_safe?(value)
+                value
+              else
+                _i18n_html_escape(value)
+              end
+          end
+        end
+
+        def _missing_translation_markup(key, error)
+          title = _i18n_html_escape(error.message)
+          body = _i18n_html_escape(key.to_s)
+          _i18n_mark_html_safe(%(<span class="translation_missing" title="#{title}">#{body}</span>))
+        end
+
+        # Escapes `value` for HTML. Prefers `Hanami::View::Helpers::EscapeHelper#escape_html` when
+        # Hanami View's EscapeHelper is included, falling back to stdlib `CGI.escapeHTML` so the
+        # helper works in API-only apps that don't bundle hanami-view.
+        def _i18n_html_escape(value)
+          if respond_to?(:escape_html)
+            escape_html(value)
+          else
+            CGI.escapeHTML(value.to_s)
+          end
+        end
+
+        # Marks the given string as HTML-safe when Hanami View is loaded, otherwise returns the
+        # string unchanged.
+        #
+        # The HTML-safe marker is only meaningful to Hanami View's template rendering, so there's
+        # nothing to do in its absence.
+        def _i18n_mark_html_safe(str)
+          str.respond_to?(:html_safe) ? str.html_safe : str
+        end
+
+        def _i18n_html_safe?(value)
+          value.respond_to?(:html_safe?) && value.html_safe?
+        end
+      end
+
+      include Methods
+
+      private
+
+      def _i18n
+        _context.i18n
+      end
+
+      def _resolve_i18n_key(key)
+        return key unless key.to_s.start_with?(".")
+
+        template_name = _context.current_template_name
+
+        unless template_name
+          raise(
+            ::I18n::ArgumentError,
+            "Cannot use relative translation key #{key.inspect} outside of a template render. " \
+            "Use an absolute key (without a leading dot) instead."
+          )
+        end
+
+        "#{template_name.tr("/", ".")}#{key}"
+      end
+    end
+  end
+end

data/lib/hanami/logger/rack_formatter.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "dry/logger"
+
+module Hanami
+  module Logger
+    # Rack request log formatter for Dry Logger.
+    #
+    # Formats rack request log entries with colorized output for HTTP verbs, status codes, and
+    # request paths, making it easier to visually scan logs in development.
+    #
+    # HTTP verbs each have a distinct color. Status codes follow traffic-light coloring (2xx green,
+    # 3xx cyan, 4xx yellow, 5xx red), and the request path echoes the status color so both signals
+    # reinforce each other at a glance.
+    #
+    # Colorization is only active when `colorize: true` is set in the logger options (the default
+    # in development).
+    #
+    # @api private
+    class RackFormatter < Dry::Logger::Formatters::String
+      RACK_TEMPLATE = <<~TEXT
+        [%<progname>s] [%<severity>s] [%<time>s] \
+        %<verb>s %<status>s %<elapsed>s %<ip>s %<path>s %<length>s %<payload>s
+          %<params>s
+      TEXT
+
+      VERB_COLORS = {
+        "GET" => :green,
+        "POST" => :yellow,
+        "PUT" => :blue,
+        "PATCH" => :blue,
+        "DELETE" => :red,
+        "HEAD" => :cyan
+      }.freeze
+
+      Colors = Dry::Logger::Formatters::Colors
+      private_constant :Colors
+
+      def initialize(**options)
+        super
+        @template = Dry::Logger::Formatters::Template[RACK_TEMPLATE]
+      end
+
+      private
+
+      def format_values(entry)
+        return super unless colorize?
+
+        status_color = status_color(entry.to_h[:status])
+
+        super.merge(
+          verb: Colors.call(VERB_COLORS.fetch(entry.to_h[:verb].to_s.upcase, :gray), entry.to_h[:verb]),
+          status: Colors.call(status_color, entry.to_h[:status]),
+          path: Colors.call(status_color, entry.to_h[:path])
+        )
+      end
+
+      def format_params(value)
+        value unless value.empty?
+      end
+
+      def status_color(status)
+        case status.to_i
+        when 200..299 then :green
+        when 300..399 then :cyan
+        when 400..499 then :yellow
+        when 500..599 then :red
+        else :gray
+        end
+      end
+    end
+  end
+end

data/lib/hanami/logger/sql_formatter.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "dry/logger"
+
+module Hanami
+  module Logger
+    # SQL query log formatter for Dry Logger.
+    #
+    # Formats SQL query log entries with a template that mirrors the structure of the built-in rack
+    # log formatter, providing consistent visual formatting across both HTTP request and database
+    # query logs.
+    #
+    # For example, in development, SQL logs alongside Rack logs:
+    #
+    #   [my_app] [INFO] [2026-03-04 10:15:32] SQL sqlite 1.234ms SELECT * FROM users
+    #   [my_app] [INFO] [2026-03-04 10:15:32] GET 200 1ms 127.0.0.1 /users -
+    #
+    # In production, the default JSON formatter handles SQL entries automatically via the structured
+    # payload.
+    #
+    # Supports colorization via Dry Logger's template color tags. When `colorize: true` is set in
+    # the logger options (the default in development), the "SQL" label is colorized, and severity
+    # is colorized per-level by the parent formatter (e.g. INFO => magenta, ERROR => red).
+    #
+    # When colorization is enabled and the "rouge" gem is available, SQL queries are syntax
+    # highlighted using Rouge's SQL lexer. This is a soft dependency; if Rouge is not installed,
+    # queries output as plain, unhighlighted text.
+    #
+    # The Rouge theme defaults to "pastie" and can be customized by setting the
+    # `HANAMI_LOG_SYNTAX_THEME` environment variable to any Rouge theme name. See
+    # `Rouge::Theme.registry` for available themes.
+    #
+    # @see Hanami::Logger::SQLLogger
+    #
+    # @api private
+    class SQLFormatter < Dry::Logger::Formatters::String
+      SQL_TEMPLATE = <<~TEXT
+        [%<progname>s] [%<severity>s] [%<time>s] SQL %<db>s %<elapsed>s%<elapsed_unit>s %<query>s
+      TEXT
+
+      SQL_TEMPLATE_COLORIZED = <<~TEXT
+        [%<progname>s] [%<severity>s] [%<time>s] <blue>SQL</blue> %<db>s %<elapsed>s%<elapsed_unit>s %<query>s
+      TEXT
+
+      def initialize(**options)
+        super
+        @template = Dry::Logger::Formatters::Template[
+          colorize? ? SQL_TEMPLATE_COLORIZED : SQL_TEMPLATE
+        ]
+        @sql_colorizer = build_sql_colorizer if colorize?
+      end
+
+      private
+
+      def format_query(value)
+        if @sql_colorizer
+          @sql_colorizer.call(value)
+        else
+          value
+        end
+      end
+
+      def build_sql_colorizer
+        begin
+          require "rouge"
+        rescue LoadError
+          return nil
+        end
+
+        theme_name = ENV.fetch("HANAMI_LOG_SYNTAX_THEME", "pastie")
+        theme_class = Rouge::Theme.find(theme_name) || Rouge::Themes::Pastie
+        formatter = Rouge::Formatters::Terminal256.new(theme_class.new)
+
+        lexer = Rouge::Lexers::SQL.new
+
+        ->(sql) { formatter.format(lexer.lex(sql)) }
+      end
+    end
+  end
+end

data/lib/hanami/logger/sql_logger.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Hanami
+  module Logger
+    # SQL query logger that integrates with the Hanami logger using structured, tagged logging.
+    #
+    # Subscribes to `:sql` notification events (emitted by ROM via the Hanami app's
+    # `"notifications"` component) and logs each query as a structured payload. The log entries are
+    # tagged as `:sql`, which allows Dry Logger backends to route them to a dedicated formatter (see
+    # {SQLFormatter}), in the same way that rack log entries are routed using the `:rack` tag.
+    #
+    # @see SQLFormatter
+    # @see Hanami::Providers::DBLogging
+    #
+    # @api private
+    class SQLLogger
+      attr_reader :logger, :level
+
+      # @param logger [#tagged, #info] a Hanami-compatible logger (typically a
+      #   Dry::Logger::Dispatcher or a {Hanami::UniversalLogger}-wrapped logger)
+      def initialize(logger, level: :debug)
+        @logger = logger
+        @level = level
+      end
+
+      # Subscribes to `:sql` notification events.
+      #
+      # @param notifications [Dry::Monitor::Notifications] the notifications bus
+      # @return [void]
+      def subscribe(notifications)
+        notifications.subscribe(:sql) { |params| log_query(**params) }
+      end
+
+      # Log a SQL query with structured data.
+      #
+      # @param time [Numeric] elapsed time in milliseconds
+      # @param name [Symbol] database adapter name (e.g. `:sqlite`, `:postgres`)
+      # @param query [String] the SQL query string
+      def log_query(time:, name:, query:)
+        logger.tagged(:sql) do
+          logger.public_send(@level) do
+            {query:, db: name, elapsed: time.round(3), elapsed_unit: "ms"}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hanami/middleware/render_errors.rb

@@ -72,9 +72,9 @@ module Hanami
         request.set_header(Rack::REQUEST_METHOD, "GET")
 
         @errors_app.call(request.env)
-      rescue Exception => failsafe_error
+      rescue Exception => exception
         # rubocop:disable Style/StderrPuts
-        $stderr.puts "Error during exception rendering: #{failsafe_error}\n  #{failsafe_error.backtrace * "\n  "}"
+        $stderr.puts "Error during exception rendering: #{exception}\n  #{exception.backtrace * "\n  "}"
         # rubocop:enable Style/StderrPuts
 
         [