.github/workflows/test.yaml

@@ -3,15 +3,15 @@ on:
   push:
     branches: [main]
   pull_request:
-    branches: [main]
+    branches: [main, release-2.0]
 permissions:
   contents: read
 jobs:
   test:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        ruby: ['3.1', '3.2', '3.3']
+        ruby: ["3.1", "3.2", "3.3"]
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4

lib/blueprinter.rb

@@ -6,6 +6,7 @@ module Blueprinter
   autoload :Configuration, 'blueprinter/configuration'
   autoload :Errors, 'blueprinter/errors'
   autoload :Extension, 'blueprinter/extension'
+  autoload :Hooks, 'blueprinter/hooks'
   autoload :Transformer, 'blueprinter/transformer'
   autoload :V2, 'blueprinter/v2'
 

lib/blueprinter/configuration.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
-require 'blueprinter/extensions'
+require 'blueprinter/hooks'
 require 'blueprinter/extractors/auto_extractor'
 
 module Blueprinter
@@ -12,6 +12,7 @@ class Configuration
       :datetime_format,
       :default_transformers,
       :deprecations,
+      :extensions,
       :extractor_default,
       :field_default,
       :generator,
@@ -20,7 +21,6 @@ class Configuration
       :sort_fields_by,
       :unless
     )
-    attr_reader :extensions
 
     VALID_CALLABLES = %i[if unless].freeze
 
@@ -37,11 +37,11 @@ def initialize
       @extractor_default = AutoExtractor
       @default_transformers = []
       @custom_array_like_classes = []
-      @extensions = Extensions.new
+      @extensions = []
     end
 
-    def extensions=(list)
-      @extensions = Extensions.new(list)
+    def hooks
+      @_hooks ||= Blueprinter::Hooks.new(extensions)
     end
 
     def array_like_classes

lib/blueprinter/extension.rb

@@ -2,21 +2,152 @@
 
 module Blueprinter
   #
-  # Base class for all extensions. All extension methods are implemented as no-ops.
+  # Base class for all extensions.
+  #
+  # V2 hook call order:
+  #  - around_hook (called around any other extension hook)
+  #  - around_object_render | around_collection_render
+  #    - input_object | input_collection
+  #    - around_object_serialization | around_collection_serialization
+  #      - prepare (only first time during a given render)
+  #      - blueprint_fields (only first time during a given render)
+  #      - blueprint_input
+  #      - field_value
+  #      - exclude_field?
+  #      - object_value
+  #      - exclude_object?
+  #      - collection_value
+  #      - exclude_collection?
+  #      - blueprint_output
+  #    - output_object | output_collection
+  #    - json
+  #
+  # V1 hook call order:
+  #  - pre_render
   #
   class Extension
-    #
-    # Called eary during "render", this method receives the object to be rendered and
+    HOOKS = %i[
+      around_hook
+      around_object_render
+      around_collection_render
+      input_object
+      input_collection
+      around_object_serialization
+      around_collection_serialization
+      prepare
+      blueprint_fields
+      blueprint_input
+      field_value
+      exclude_field?
+      object_value
+      exclude_object?
+      collection_value
+      exclude_collection?
+      blueprint_output
+      output_object
+      output_collection
+      json
+      pre_render
+    ].freeze
+
+    # If this returns true, around_hook will not be called when this extension's hooks are run. Used by core extensions.
+    def hidden? = false
+
+    # around_object_render: Runs around the entire rendering process for an object. MUST yield!
+    # @param context [Blueprinter::V2::Context::Object]
+
+    # around_collection_render: Runs around the entire rendering process for a collection. MUST yield!
+    # @param context [Blueprinter::V2::Context::Object]
+
+    # around_object_serialization: Runs around serialization of a Blueprint object. Surrounds the `prepare` through
+    # `blueprint_output` hooks. MUST yield!
+    # @param context [Blueprinter::V2::Context::Object]
+
+    # around_collection_serialization: Runs around serialization of a Blueprint collection. Surrounds the `prepare` through
+    # `blueprint_output` hooks. MUST yield!
+    # @param context [Blueprinter::V2::Context::Object]
+
+    # prepare: Called once per blueprint per render. A common use is to pre-calculate certain options
+    # and cache them in context.data, so we don't have to recalculate them for every field.
+    # @param context [Blueprinter::V2::Context::Render]
+
+    # blueprint_fields: Returns the fields that should be included in the correct order. Default is all fields in the order
+    # in which they were defined.
+    # NOTE Only runs once per Blueprint per render.
+    # @param context [Blueprinter::V2::Context::Render]
+    # @return [Array<Blueprinter::V2::Field|Blueprinter::V2::Object|Blueprinter::V2::Collection>]
+
+    # input_object: Modify or replace the object passed to render/render_object. The returned object is what will be
+    # rendered.
+    # @param context [Blueprinter::V2::Context::Object]
+    # @return [Object]
+
+    # input_collection: Modify or replace the collection passed to render/render_collection. The returned collection is what
+    # will be rendered.
+    # @param context [Blueprinter::V2::Context::Object]
+    # @return [Object]
+
+    # output_object: Modify or replace the object result (stored in context.value) before final render (e.g. to JSON). The
+    # returned object is what will be rendered.
+    # @param context [Blueprinter::V2::Context::Result]
+    # @return [Object]
+
+    # output_collection: Modify or replace the collection result (stored in context.value) before final render (e.g. to
+    # JSON). The returned object is what will be rendered.
+    # @param context [Blueprinter::V2::Context::Result]
+    # @return [Object]
+
+    # blueprint_input: Modify or replace an object right before it's serialized by a Blueprint. The returned object will be
+    # used as the input to the Blueprint.
+    # @param context [Blueprinter::V2::Context::Object]
+    # @return [Object]
+
+    # blueprint_output: Modify or replace the serialized output from any Blueprint. The returned object will be used as the
+    # output of the Blueprint.
+    # @param context [Blueprinter::V2::Context::Result]
+    # @return [Object]
+
+    # field_value: Modify or replace the value used for the field. The returned value will be run through any formatters and
+    # used as the field's value.
+    # @param context [Blueprinter::V2::Context::Field]
+    # @return [Object]
+
+    # object_value: Modify or replace the value used for the object. The returned value will be used as the input for the
+    # object's Blueprint.
+    # @param context [Blueprinter::V2::Context::Field]
+    # @return [Object]
+
+    # collection_value: Modify or replace the value used for the collection. The returned value will be used as the input for
+    # the collection's Blueprint.
+    # @param context [Blueprinter::V2::Context::Field]
+    # @return [Object]
+
+    # exclude_field?: Return true to exclude this field from the result.
+    # @param context [Blueprinter::V2::Context::Field]
+    # @return [Boolean]
+
+    # exclude_object?: Return true to exclude this object from the result.
+    # @param context [Blueprinter::V2::Context::Field]
+    # @return [Boolean]
+
+    # exclude_collection?: Return true to exclude this collection from the result.
+    # @param context [Blueprinter::V2::Context::Field]
+    # @return [Boolean]
+
+    # json: Override the default JSON encoder. The returned string will be the JSON output.
+    # @param context [Blueprinter::V2::Context::Result]
+    # @return [String]
+
+    # around_hook: Instrument extension hook calls. MUST yield!
+    # @param extension [Blueprinter::Extension] Instance of the extension
+    # @param hook [Symbol] Name of hook being called
+
+    # pre_render: Called eary during "render" in V1, this method receives the object to be rendered and
     # may return a modified (or new) object to be rendered.
-    #
     # @param object [Object] The object to be rendered
-    # @param _blueprint [Class] The Blueprinter class
-    # @param _view [Symbol] The blueprint view
-    # @param _options [Hash] Options passed to "render"
+    # @param blueprint [Class] The Blueprinter class
+    # @param view [Symbol] The blueprint view
+    # @param options [Hash] Options passed to "render"
     # @return [Object] The object to continue rendering
-    #
-    def pre_render(object, _blueprint, _view, _options)
-      object
-    end
   end
 end