{"id":15653148,"url":"https://github.com/jordanrl/newton","last_synced_at":"2025-06-13T08:07:33.593Z","repository":{"id":62539848,"uuid":"41317662","full_name":"JordanRL/Newton","owner":"JordanRL","description":"A library providing physics units which are fully aware of each other, and which can have math operations performed on them.","archived":false,"fork":false,"pushed_at":"2018-04-09T22:44:29.000Z","size":107,"stargazers_count":30,"open_issues_count":4,"forks_count":2,"subscribers_count":3,"default_branch":"dev","last_synced_at":"2025-04-30T21:11:19.845Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JordanRL.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-08-24T17:39:07.000Z","updated_at":"2022-12-30T21:00:41.000Z","dependencies_parsed_at":"2022-11-02T15:45:18.089Z","dependency_job_id":null,"html_url":"https://github.com/JordanRL/Newton","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/JordanRL/Newton","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JordanRL%2FNewton","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JordanRL%2FNewton/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JordanRL%2FNewton/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JordanRL%2FNewton/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JordanRL","download_url":"https://codeload.github.com/JordanRL/Newton/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JordanRL%2FNewton/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259606974,"owners_count":22883559,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T12:44:49.467Z","updated_at":"2025-06-13T08:07:33.563Z","avatar_url":"https://github.com/JordanRL.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Newton\r\n\r\n[![Build Status](https://travis-ci.org/JordanRL/Newton.svg?branch=master)](https://travis-ci.org/JordanRL/Newton) [![Coverage Status](https://coveralls.io/repos/JordanRL/Newton/badge.svg?branch=master\u0026service=github)](https://coveralls.io/github/JordanRL/Newton?branch=master) [![Latest Stable Version](https://poser.pugx.org/samsara/newton/v/stable)](https://packagist.org/packages/samsara/newton) [![Total Downloads](https://poser.pugx.org/samsara/newton/downloads)](https://packagist.org/packages/samsara/newton) [![Latest Unstable Version](https://poser.pugx.org/samsara/newton/v/unstable)](https://packagist.org/packages/samsara/newton) [![License](https://poser.pugx.org/samsara/newton/license)](https://packagist.org/packages/samsara/newton)\r\n\r\n**This project is unit tested against 5.6.X and 7.X, and merges are not accepted unless the tests pass on both.**\r\n\r\n## Installation\r\n\r\nTo install, simply require the package using composer:\r\n\r\n    composer require samsara/newton \"1.*\"\r\n    \r\nOr include it in your `composer.json` file:\r\n\r\n```json\r\n{\r\n    \"require\": {\r\n        \"samsara/newton\": \"1.*\"\r\n    }\r\n}\r\n```\r\n\r\nThe project namespace is `Samsara\\Newton\\*`. You can view the project on [Packagist](https://packagist.org/packages/samsara/newton).\r\n\r\n## Usage\r\n\r\nThere are many ways to use this package. The preferred way involves instantiating the UnitComposition class and using it as a factory.\r\n\r\nIn order to allow new unit classes which extend Quantity to work with the UnitComposition class, it was necessary to force instantiation of it. This is explained in further detail in the **Extending** section.\r\n\r\nThis also means that if you directly instantiate a unit, you must inject a UnitComposition instance.\r\n\r\n```php\r\n$unitComposition = new Samsara\\Newton\\Core\\UnitComposition();\r\n\r\n$thrust = $unitComposition-\u003egetUnitClass(UnitComposition::FORCE, 1000); \r\necho $thrust; // 1000 Newtons\r\n$mass = $unitComposition-\u003egetUnitClass(UnitComposition::MASS, 1000); \r\necho $mass; // 1000 kg\r\n\r\n$acceleration = $thrust-\u003edivideBy($mass);\r\n\r\necho $acceleration; // 1 m/s^2\r\n\r\n$acceleration-\u003eaddAlias('N/kg', 'm/s^2')-\u003eto('N/kg'); \r\n\r\necho $acceleration; // 1 N/kg [Gravitational field strength]\r\n```\r\n\r\nYou can also add unit of different types.\r\n\r\n```php\r\n$unitComposition = new Samsara\\Newton\\Core\\UnitComposition();\r\n\r\n$thrust = $unitComposition-\u003egetUnitClass(UnitComposition::FORCE, 1000); \r\necho $thrust; // 1000 Newtons\r\n$mass = $unitComposition-\u003egetUnitClass(UnitComposition::MASS, 500); \r\necho $mass; // 500 kg\r\n\r\n$mass2 = new Mass(5, $unitComposition, 't'); // 't' = metric ton = 1000kg\r\n\r\n$mass-\u003eadd($mass2);\r\necho $mass; // 5500 kg;\r\n```\r\n\r\nThe **MathProvider** has static methods which allow you to perform math operations using the BC Math extension. This is used internally in the project as we might very easily exceed the PHP_INT_MAX limit during unit conversions. It also provides several random functions, including a gaussianRandom() method.\r\n\r\nThe **PhysicsProvider** has static methods which implement some common physics equations using the correct unit classes.\r\n\r\nAn interesting, non-physics use for something like this library is to determine how many times a given server can execute a loop per second. For instance:\r\n\r\n```php\r\n$unitComposition = new UnitComposition();\r\n\r\n$start = microtime(true);\r\nfor ($i = 0;$i \u003c 10000;$i++) {\r\n    // Loop to test\r\n}\r\n$end = microtime(true);\r\n\r\n$duration = $end - $start;\r\n$durationInMilliseconds = $duration * 1000;\r\n\r\n$time = new Time($durationInMilliseconds, $unitComposition, 'ms');\r\n$cycles = new Cycles(10000, $unitComposition);\r\n\r\n$loopsPerSecond = $unitComposition-\u003enaiveDivide($cycles, $time);\r\n\r\n// The number of times, as measured, that the computer can execute the loop\r\n// in a single second.\r\necho $loopsPerSecond-\u003egetValue();\r\n```\r\n\r\n## Extending\r\n\r\nAdding new units is relatively easy. You must first make your unit class, and this class must extend `Samsara\\Newton\\Core\\Quantity`. This class must define a set of units in the `$units` property (where it defines the index for `$rates`), and then define the relative conversion rates between them.\r\n\r\nAll of the conversions must be in terms of the **native** unit, which is defined in the property `$native`.\r\n\r\n### Example\r\n\r\n```php\r\nuse Samsara\\Newton\\Core\\Quantity;\r\nuse Samsara\\Newton\\Core\\UnitComposition;\r\n\r\nclass MyUnit extends Quantity\r\n{\r\n    const SOMEUNIT = 'g';\r\n    const BIGUNIT = 'bg';\r\n    \r\n    protected $units = [\r\n        // It is the first index in the rates array\r\n        self::SOMEUNIT =\u003e 1, \r\n        self::BIGUNIT =\u003e 2\r\n    ];\r\n    \r\n    protected $native = self::SOMEUNIT;\r\n    \r\n    public function __construct($value, UnitComposition $unitComposition, $unit = null)\r\n    {\r\n        $this-\u003erates = [\r\n            // Almost always the 'native' unit is set equal to 1\r\n            $this-\u003eunits[self::SOMEUNIT] =\u003e '1', \r\n            $this-\u003eunits[self::BIGUNIT] =\u003e '1000',\r\n        ];\r\n        \r\n        parent::__construct($value, $unitComposition, $unit)\r\n        \r\n        $this-\u003esetComposition($unitComposition-\u003edynamicUnits['MyUnit']);\r\n    }\r\n}\r\n```\r\n\r\nThen, in the calling context, you must prepare the UnitComposition class with the definitions of what types of units this custom unit contains. This allows the UnitComposition class to automatically use your custom class in multiply and divide operations when it is appropriate to do so.\r\n\r\n```php\r\n$unitComposition = new UnitComposition();\r\n\r\n// This will automatically instatiate the class Namespaced\\MyUnit()\r\n// when 'time' has an exponent of 2, and 'mass' has an exponent of 1\r\n// after multiply or divide operations using the naive*() methods.\r\n//\r\n// The last argument defines how you can refer to the unit in the \r\n// factory method: getUnitClass()\r\n$unitComposition-\u003eaddUnit('Namespaced\\\\MyUnit', ['time' =\u003e 2, 'mass' =\u003e 1], 'MyUnit');\r\n\r\n// Now we can instantiate two ways:\r\n\r\n// $myunit is now an object of type MyUnit, in its native units, with a value of zero\r\n$myunit = $unitComposition-\u003egetUnitClass('MyUnit'); \r\n// Object of MyUnit type in native units with value 1000\r\n$myunit2 = $unitComposition-\u003egetUnitClass('MyUnit', 1000); \r\n\r\n// OR\r\n\r\n// MyUnit object in BIGUNIT with value 1 == 1000 in SOMEUNIT\r\n$myunit3 = new Namespaced\\MyUnit(1, $unitComposition, 'bg'); \r\n\r\n// We can add them if we want\r\n\r\n// Automatically converts. $myunit3 now has value of 2 and units of BIGUNIT.\r\n$myunit3-\u003eadd($myunit2)-\u003eadd($myunit); \r\n```\r\n\r\nOnly the instance of UnitComposition prepared in the way outlined above, with a call to addUnit(), will understand how to automatically return an instance of MyUnit(). Because of this, it is suggested that you treat the UnitComposition class as a service, and use a single instance of it within your application.\r\n\r\n## Contributing\r\n\r\nPlease ensure that pull requests meet the following guidelines:\r\n\r\n- New files created in the pull request must have a corresponding unit test file, or must be covered within an existing test file.\r\n- Your merge may not drop the project's test coverage below 85%.\r\n- Your merge may not drop the project's test coverage by MORE than 5%.\r\n- Your merge must pass Travis-CI build tests for BOTH PHP 5.6.X and PHP 7.X.\r\n\r\nFor more information, please see the section on [Contributing](CONTRIBUTING.md)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjordanrl%2Fnewton","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjordanrl%2Fnewton","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjordanrl%2Fnewton/lists"}