Skip to content

Commit 247c892

Browse files
rafaelfrancarafaelfranca
committed
Move load hooks section to the configuration guide
Those also applies to applications, so they should not be in a guide specific for engines.
1 parent 8922180 commit 247c892

File tree

2 files changed

+129
-154
lines changed

2 files changed

+129
-154
lines changed

‎guides/source/configuring.md

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3453,6 +3453,135 @@ NOTE: There is no guarantee that your initializers will run after all the gem
34533453
initializers, so any initialization code that depends on a given gem having been
34543454
initialized should go into a `config.after_initialize` block.
34553455
3456+
Load Hooks
3457+
----------------------------
3458+
3459+
Rails code can often be referenced on load of an application. Rails is responsible for the load order of these frameworks, so when you load frameworks, such as `ActiveRecord::Base`, prematurely you are violating an implicit contract your application has with Rails. Moreover, by loading code such as `ActiveRecord::Base` on boot of your application you are loading entire frameworks which may slow down your boot time and could cause conflicts with load order and boot of your application.
3460+
3461+
Load and configuration hooks are the API that allow you to hook into this initialization process without violating the load contract with Rails. This will also mitigate boot performance degradation and avoid conflicts.
3462+
3463+
### Avoid Loading Rails Frameworks
3464+
3465+
Since Ruby is a dynamic language, some code will cause different Rails frameworks to load. Take this snippet for instance:
3466+
3467+
```ruby
3468+
ActiveRecord::Base.include(MyActiveRecordHelper)
3469+
```
3470+
3471+
This snippet means that when this file is loaded, it will encounter `ActiveRecord::Base`. This encounter causes Ruby to look for the definition of that constant and will require it. This causes the entire Active Record framework to be loaded on boot.
3472+
3473+
`ActiveSupport.on_load` is a mechanism that can be used to defer the loading of code until it is actually needed. The snippet above can be changed to:
3474+
3475+
```ruby
3476+
ActiveSupport.on_load(:active_record) do
3477+
include MyActiveRecordHelper
3478+
end
3479+
```
3480+
3481+
This new snippet will only include `MyActiveRecordHelper` when `ActiveRecord::Base` is loaded.
3482+
3483+
### When are Hooks called?
3484+
3485+
In the Rails framework these hooks are called when a specific library is loaded. For example, when `ActionController::Base` is loaded, the `:action_controller_base` hook is called. This means that all `ActiveSupport.on_load` calls with `:action_controller_base` hooks will be called in the context of `ActionController::Base` (that means `self` will be an `ActionController::Base`).
3486+
3487+
### Modifying Code to Use Load Hooks
3488+
3489+
Modifying code is generally straightforward. If you have a line of code that refers to a Rails framework such as `ActiveRecord::Base` you can wrap that code in a load hook.
3490+
3491+
**Modifying calls to `include`**
3492+
3493+
```ruby
3494+
ActiveRecord::Base.include(MyActiveRecordHelper)
3495+
```
3496+
3497+
becomes
3498+
3499+
```ruby
3500+
ActiveSupport.on_load(:active_record) do
3501+
# self refers to ActiveRecord::Base here,
3502+
# so we can call .include
3503+
include MyActiveRecordHelper
3504+
end
3505+
```
3506+
3507+
**Modifying calls to `prepend`**
3508+
3509+
```ruby
3510+
ActionController::Base.prepend(MyActionControllerHelper)
3511+
```
3512+
3513+
becomes
3514+
3515+
```ruby
3516+
ActiveSupport.on_load(:action_controller_base) do
3517+
# self refers to ActionController::Base here,
3518+
# so we can call .prepend
3519+
prepend MyActionControllerHelper
3520+
end
3521+
```
3522+
3523+
**Modifying calls to class methods**
3524+
3525+
```ruby
3526+
ActiveRecord::Base.include_root_in_json = true
3527+
```
3528+
3529+
becomes
3530+
3531+
```ruby
3532+
ActiveSupport.on_load(:active_record) do
3533+
# self refers to ActiveRecord::Base here
3534+
self.include_root_in_json = true
3535+
end
3536+
```
3537+
3538+
### Available Load Hooks
3539+
3540+
These are the load hooks you can use in your own code. To hook into the initialization process of one of the following classes use the available hook.
3541+
3542+
| Class | Hook |
3543+
| -------------------------------------| ------------------------------------ |
3544+
| `ActionCable` | `action_cable` |
3545+
| `ActionCable::Channel::Base` | `action_cable_channel` |
3546+
| `ActionCable::Connection::Base` | `action_cable_connection` |
3547+
| `ActionCable::Connection::TestCase` | `action_cable_connection_test_case` |
3548+
| `ActionController::API` | `action_controller_api` |
3549+
| `ActionController::API` | `action_controller` |
3550+
| `ActionController::Base` | `action_controller_base` |
3551+
| `ActionController::Base` | `action_controller` |
3552+
| `ActionController::TestCase` | `action_controller_test_case` |
3553+
| `ActionDispatch::IntegrationTest` | `action_dispatch_integration_test` |
3554+
| `ActionDispatch::Response` | `action_dispatch_response` |
3555+
| `ActionDispatch::Request` | `action_dispatch_request` |
3556+
| `ActionDispatch::SystemTestCase` | `action_dispatch_system_test_case` |
3557+
| `ActionMailbox::Base` | `action_mailbox` |
3558+
| `ActionMailbox::InboundEmail` | `action_mailbox_inbound_email` |
3559+
| `ActionMailbox::Record` | `action_mailbox_record` |
3560+
| `ActionMailbox::TestCase` | `action_mailbox_test_case` |
3561+
| `ActionMailer::Base` | `action_mailer` |
3562+
| `ActionMailer::TestCase` | `action_mailer_test_case` |
3563+
| `ActionText::Content` | `action_text_content` |
3564+
| `ActionText::Record` | `action_text_record` |
3565+
| `ActionText::RichText` | `action_text_rich_text` |
3566+
| `ActionText::EncryptedRichText` | `action_text_encrypted_rich_text` |
3567+
| `ActionView::Base` | `action_view` |
3568+
| `ActionView::TestCase` | `action_view_test_case` |
3569+
| `ActiveJob::Base` | `active_job` |
3570+
| `ActiveJob::TestCase` | `active_job_test_case` |
3571+
| `ActiveModel::Model` | `active_model` |
3572+
| `ActiveRecord::Base` | `active_record` |
3573+
| `ActiveRecord::TestFixtures` | `active_record_fixtures` |
3574+
| `ActiveRecord::ConnectionAdapters::PostgreSQLAdapter` | `active_record_postgresqladapter` |
3575+
| `ActiveRecord::ConnectionAdapters::Mysql2Adapter` | `active_record_mysql2adapter` |
3576+
| `ActiveRecord::ConnectionAdapters::TrilogyAdapter` | `active_record_trilogyadapter` |
3577+
| `ActiveRecord::ConnectionAdapters::SQLite3Adapter` | `active_record_sqlite3adapter` |
3578+
| `ActiveStorage::Attachment` | `active_storage_attachment` |
3579+
| `ActiveStorage::VariantRecord` | `active_storage_variant_record` |
3580+
| `ActiveStorage::Blob` | `active_storage_blob` |
3581+
| `ActiveStorage::Record` | `active_storage_record` |
3582+
| `ActiveSupport::TestCase` | `active_support_test_case` |
3583+
| `i18n` | `i18n` |
3584+
34563585
Initialization Events
34573586
---------------------
34583587

‎guides/source/engines.md

Lines changed: 0 additions & 154 deletions
Original file line numberDiff line numberDiff line change
@@ -1369,157 +1369,3 @@ module MyEngine
13691369
end
13701370
end
13711371
```
1372-
1373-
Load and Configuration Hooks
1374-
----------------------------
1375-
1376-
Rails code can often be referenced on load of an application. Rails is responsible for the load order of these frameworks, so when you load frameworks, such as `ActiveRecord::Base`, prematurely you are violating an implicit contract your application has with Rails. Moreover, by loading code such as `ActiveRecord::Base` on boot of your application you are loading entire frameworks which may slow down your boot time and could cause conflicts with load order and boot of your application.
1377-
1378-
Load and configuration hooks are the API that allow you to hook into this initialization process without violating the load contract with Rails. This will also mitigate boot performance degradation and avoid conflicts.
1379-
1380-
### Avoid Loading Rails Frameworks
1381-
1382-
Since Ruby is a dynamic language, some code will cause different Rails frameworks to load. Take this snippet for instance:
1383-
1384-
```ruby
1385-
ActiveRecord::Base.include(MyActiveRecordHelper)
1386-
```
1387-
1388-
This snippet means that when this file is loaded, it will encounter `ActiveRecord::Base`. This encounter causes Ruby to look for the definition of that constant and will require it. This causes the entire Active Record framework to be loaded on boot.
1389-
1390-
`ActiveSupport.on_load` is a mechanism that can be used to defer the loading of code until it is actually needed. The snippet above can be changed to:
1391-
1392-
```ruby
1393-
ActiveSupport.on_load(:active_record) do
1394-
include MyActiveRecordHelper
1395-
end
1396-
```
1397-
1398-
This new snippet will only include `MyActiveRecordHelper` when `ActiveRecord::Base` is loaded.
1399-
1400-
### When are Hooks called?
1401-
1402-
In the Rails framework these hooks are called when a specific library is loaded. For example, when `ActionController::Base` is loaded, the `:action_controller_base` hook is called. This means that all `ActiveSupport.on_load` calls with `:action_controller_base` hooks will be called in the context of `ActionController::Base` (that means `self` will be an `ActionController::Base`).
1403-
1404-
### Modifying Code to Use Load Hooks
1405-
1406-
Modifying code is generally straightforward. If you have a line of code that refers to a Rails framework such as `ActiveRecord::Base` you can wrap that code in a load hook.
1407-
1408-
**Modifying calls to `include`**
1409-
1410-
```ruby
1411-
ActiveRecord::Base.include(MyActiveRecordHelper)
1412-
```
1413-
1414-
becomes
1415-
1416-
```ruby
1417-
ActiveSupport.on_load(:active_record) do
1418-
# self refers to ActiveRecord::Base here,
1419-
# so we can call .include
1420-
include MyActiveRecordHelper
1421-
end
1422-
```
1423-
1424-
**Modifying calls to `prepend`**
1425-
1426-
```ruby
1427-
ActionController::Base.prepend(MyActionControllerHelper)
1428-
```
1429-
1430-
becomes
1431-
1432-
```ruby
1433-
ActiveSupport.on_load(:action_controller_base) do
1434-
# self refers to ActionController::Base here,
1435-
# so we can call .prepend
1436-
prepend MyActionControllerHelper
1437-
end
1438-
```
1439-
1440-
**Modifying calls to class methods**
1441-
1442-
```ruby
1443-
ActiveRecord::Base.include_root_in_json = true
1444-
```
1445-
1446-
becomes
1447-
1448-
```ruby
1449-
ActiveSupport.on_load(:active_record) do
1450-
# self refers to ActiveRecord::Base here
1451-
self.include_root_in_json = true
1452-
end
1453-
```
1454-
1455-
### Available Load Hooks
1456-
1457-
These are the load hooks you can use in your own code. To hook into the initialization process of one of the following classes use the available hook.
1458-
1459-
| Class | Hook |
1460-
| -------------------------------------| ------------------------------------ |
1461-
| `ActionCable` | `action_cable` |
1462-
| `ActionCable::Channel::Base` | `action_cable_channel` |
1463-
| `ActionCable::Connection::Base` | `action_cable_connection` |
1464-
| `ActionCable::Connection::TestCase` | `action_cable_connection_test_case` |
1465-
| `ActionController::API` | `action_controller_api` |
1466-
| `ActionController::API` | `action_controller` |
1467-
| `ActionController::Base` | `action_controller_base` |
1468-
| `ActionController::Base` | `action_controller` |
1469-
| `ActionController::TestCase` | `action_controller_test_case` |
1470-
| `ActionDispatch::IntegrationTest` | `action_dispatch_integration_test` |
1471-
| `ActionDispatch::Response` | `action_dispatch_response` |
1472-
| `ActionDispatch::Request` | `action_dispatch_request` |
1473-
| `ActionDispatch::SystemTestCase` | `action_dispatch_system_test_case` |
1474-
| `ActionMailbox::Base` | `action_mailbox` |
1475-
| `ActionMailbox::InboundEmail` | `action_mailbox_inbound_email` |
1476-
| `ActionMailbox::Record` | `action_mailbox_record` |
1477-
| `ActionMailbox::TestCase` | `action_mailbox_test_case` |
1478-
| `ActionMailer::Base` | `action_mailer` |
1479-
| `ActionMailer::TestCase` | `action_mailer_test_case` |
1480-
| `ActionText::Content` | `action_text_content` |
1481-
| `ActionText::Record` | `action_text_record` |
1482-
| `ActionText::RichText` | `action_text_rich_text` |
1483-
| `ActionText::EncryptedRichText` | `action_text_encrypted_rich_text` |
1484-
| `ActionView::Base` | `action_view` |
1485-
| `ActionView::TestCase` | `action_view_test_case` |
1486-
| `ActiveJob::Base` | `active_job` |
1487-
| `ActiveJob::TestCase` | `active_job_test_case` |
1488-
| `ActiveModel::Model` | `active_model` |
1489-
| `ActiveRecord::Base` | `active_record` |
1490-
| `ActiveRecord::TestFixtures` | `active_record_fixtures` |
1491-
| `ActiveRecord::ConnectionAdapters::PostgreSQLAdapter` | `active_record_postgresqladapter` |
1492-
| `ActiveRecord::ConnectionAdapters::Mysql2Adapter` | `active_record_mysql2adapter` |
1493-
| `ActiveRecord::ConnectionAdapters::TrilogyAdapter` | `active_record_trilogyadapter` |
1494-
| `ActiveRecord::ConnectionAdapters::SQLite3Adapter` | `active_record_sqlite3adapter` |
1495-
| `ActiveStorage::Attachment` | `active_storage_attachment` |
1496-
| `ActiveStorage::VariantRecord` | `active_storage_variant_record` |
1497-
| `ActiveStorage::Blob` | `active_storage_blob` |
1498-
| `ActiveStorage::Record` | `active_storage_record` |
1499-
| `ActiveSupport::TestCase` | `active_support_test_case` |
1500-
| `i18n` | `i18n` |
1501-
1502-
### Available Configuration Hooks
1503-
1504-
Configuration hooks do not hook into any particular framework, but instead they run in context of the entire application.
1505-
1506-
| Hook | Use Case |
1507-
| ---------------------- | ---------------------------------------------------------------------------------- |
1508-
| `before_configuration` | First configurable block to run. Called before any initializers are run. |
1509-
| `before_initialize` | Second configurable block to run. Called before frameworks initialize. |
1510-
| `before_eager_load` | Third configurable block to run. Does not run if [`config.eager_load`][] set to false. |
1511-
| `after_initialize` | Last configurable block to run. Called after frameworks initialize. |
1512-
1513-
Configuration hooks can be called in the Engine class.
1514-
1515-
```ruby
1516-
module Blorgh
1517-
class Engine < ::Rails::Engine
1518-
config.before_configuration do
1519-
puts 'I am called before any initializers'
1520-
end
1521-
end
1522-
end
1523-
```
1524-
1525-
[`config.eager_load`]: configuring.html#config-eager-load

0 commit comments

Comments
 (0)