train-horn / yii2-sound-level
Yii 2 extension: sound pressure level at distance (inverse-square law with optional air absorption), level addition, an accessible table widget and a console command.
Package info
github.com/train-horn/yii2-sound-level
Type:yii2-extension
pkg:composer/train-horn/yii2-sound-level
Requires
- php: >=7.4
- yiisoft/yii2: ~2.0.45
Requires (Dev)
- phpunit/phpunit: ^9.6 || ^10.5 || ^11.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is not auto-updated.
Last update: 2026-11-19 19:59:35 UTC
README
A Yii 2 extension that estimates sound pressure level (SPL) at a distance from a level known at a reference distance, e.g. "150 dB at 10 ft". It uses the free-field inverse-square law with an optional air-absorption term, and can add levels from several sources.
It is a PHP port of the calculator behind the Train Horn decibel-at-distance tool, with the same formulas and the same test vectors. Maintained by Train Horn, an independent reference on train horns.
What you get:
SoundLevel: an application component (level at distance, inverse, level addition, distance-ratio loss).SoundLevelTable: a widget that renders an accessible HTML table for a list of distances.sound-level: a console command, e.g.yii sound-level/table 150 10.
Installation
composer require train-horn/yii2-sound-level
Requires PHP 7.4+ and Yii 2.0.45+. Tested with PHP 8.5 and Yii 2.0.55.
The model
L(d) = L_ref - 20 * log10(d / d_ref) - alpha * (d - d_ref) / 1000
L_ref: level in dB at the reference distanced_ref(ratings are often quoted "at 10 ft" or "at 1 m").alpha: optional air absorption in dB/km, applied to the extra path (distances converted to metres). Default 0.- Each doubling of distance costs about 6.02 dB; ten times the distance costs 20 dB.
- Incoherent sources add as
10 * log10(sum(10^(L_i/10))), so two equal horns add about 3 dB.
SoundLevel::AIR_ABSORPTION_DB_PER_KM holds rounded typical values by octave band
(10 degC, 70 % RH, after ISO 9613-1/9613-2). For horn frequencies (about 250-600 Hz) absorption is
only 1-2 dB/km, so it matters only at long range.
Limits: free field only. Ground reflection, barriers, wind and temperature gradients are ignored, and the law does not hold very close to the source. The results are estimates, not measurements, and not a legal noise assessment.
Component
// config/web.php or config/console.php 'components' => [ 'soundLevel' => [ 'class' => \trainhorn\soundlevel\SoundLevel::class, 'refDistance' => 10, // default reference distance 'unit' => 'ft', // 'ft' or 'm' 'absorptionDbPerKm' => 0, // 0 = pure inverse-square law ], ],
$spl = Yii::$app->soundLevel; $spl->splAtDistance(150, 100); // 130.0 (150 dB at 10 ft -> 100 ft) $spl->splAtDistance(120, 10, 1, 'm'); // 100.0 (120 dB at 1 m -> 10 m) $spl->splAtDistance(150, 1010, 10, 'm', 2); // 107.91 (with 2 dB/km absorption) $spl->distanceForSpl(150, 90); // 10000.0 ft $spl->combineLevels([100, 100]); // 103.01 $spl->doublingLoss(); // 6.02 $spl->table(150, [10, 100, 1000]); // [['distance' => 10.0, 'level' => 150.0], ...]
Every argument after the first two is optional and falls back to the component defaults.
Invalid input (non-numeric, NaN/INF, distance <= 0, negative absorption, unknown unit)
throws trainhorn\soundlevel\InvalidInputException, a subclass of yii\base\InvalidArgumentException.
Widget
use trainhorn\soundlevel\widgets\SoundLevelTable; echo SoundLevelTable::widget([ 'sourceDb' => 150, 'refDistance' => 10, 'unit' => 'ft', 'distances' => [10, 50, 100, 500, 1000], // 'absorptionDbPerKm' => 1.9, // 'calculator' => 'soundLevel', // use the configured component's defaults // 'caption' => 'Horn A', // 'options' => ['class' => 'table table-sm'], ]);
The table has a <caption>, column headers with scope="col" and one row header with
scope="row" per distance, so screen readers read each level together with its distance.
Console command
The extension registers the sound-level command in console applications automatically
(Composer extra.bootstrap). To register it by hand:
'controllerMap' => ['sound-level' => \trainhorn\soundlevel\console\SoundLevelController::class].
$ ./yii sound-level/table 150 10
Distance (ft) Level (dB)
10 150.0
25 142.0
50 136.0
100 130.0
250 122.0
500 116.0
1000 110.0
2500 102.0
5000 96.0
Free-field estimate, not a measurement.
$ ./yii sound-level/table 120 1 --unit=m --distances=1,10,100,1000 --absorption=1.9
$ ./yii sound-level/at 150 100 # 130.0 dB
$ ./yii sound-level/distance 150 90 # 10000 ft
$ ./yii sound-level/combine 100,100 # 103.0 dB
Invalid input prints an error to stderr and exits with code 65 (ExitCode::DATAERR).
Tests
composer install vendor/bin/phpunit
40 tests cover the known values (150 dB at 10 ft gives 130.0 dB at 100 ft), round trips with and without absorption, level addition, the widget markup, the console command and invalid input.
License
MIT. See LICENSE.