diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..2434eda --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2023 Yaseen Ahmed + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..7dcb8cc --- /dev/null +++ b/README.md @@ -0,0 +1,170 @@ +# Phone-Number-Info Laravel Package + +## Introduction + +Phone-Number-Info is a Laravel package that provides useful information related to phone numbers, including Home Location Register (HLR) insights, number types, original network details, and more. + +## Features +The Phone-Number-Info Laravel package comes with the following features: + +1. Phone Number Validation: + - Validate the format and correctness of phone numbers. + +2. HLR Lookups: + - Perform Home Location Register (HLR) lookups to determine the real-time status and information of phone numbers. + +3. Number Type Detection: + - Detect the type of phone number, such as mobile or landline. + +4. Original Network Details: + - Retrieve details about the original network provider of the phone number. + +5. Number Porting Detection: + - Identify if the phone number has been ported between different carriers. + +6. SMS and MMS Email Addresses: + - Obtain the SMS and MMS email addresses associated with the phone number. + +7. Credits Management: + - Keep track of the number of credits spent for API requests and usage. + +8. Request Parameters: + - Access and analyze the parameters used in the API request for phone number information. + +## Prerequisites +Before using the Phone-Number-Info Laravel package, you must fulfill the following prerequisites: + +1. **API Key and API Secret from hlrlookup.com**: + - To access HLR data and perform phone number lookups, you need an API key and API secret from hlrlookup.com. Visit their website (https://hlrlookup.com) to sign up for an account and obtain the required credentials. Note that hlrlookup.com may have specific usage limits and pricing policies for their API services. + +2. **PHP 7.4 or higher**: + - Ensure that your server environment has PHP 7.4 or a higher version installed, as the package requires this minimum PHP version to function correctly. + +3. **Laravel 8.0 or higher**: + - Phone-Number-Info Laravel package requires Laravel 8.0 or a higher version. Make sure you have a compatible Laravel framework set up in your project. + +### Installation + +You can install the package via Composer. Run the following command in your terminal: + +```bash +composer require bytes4sale/phone-number-info +``` + +## Configuration +Before using this package, you need to set your API key and API Secret in the .env file of your Laravel project. + +1. Open your Laravel project's root directory. +2. Create or modify the `.env` file and add: + +```php +API_KEY=your_hlrlookup_api_key_here +API_SECRET=your_hlrlookup_api_secret_here, + +``` + +## Usage + +Getting information for a Phone Number is a breeze with phone-number-info. Simply follow these steps: + +1. **Initialize phone-number-info**: Before using the package, make sure to initialize it. You can do this by adding the `ServiceProvider` to the `config/app.php` file: + + ```php + // config/app.php + + 'providers' => [ + // Other providers... + Bytes4sale\PhoneNumberInfo\PhoneNumberInfoServiceProvider::class, + ], + +2. **Retrieve Number Information**: Once the package is initialized, you can easily get the details for a Phone Number: + + ```php + use Bytes4sale\PhoneNumberInfo\Facades\PhoneNumberInfo; + + // Get information for a single phone number + $phoneNumber = '921234567874'; + $response = PhoneNumberInfo::getHlrDetails($phoneNumber); + if ($response->isSuccessful()) { + print_r($response->getContent()); + } else{ + print_r($response->getErrorResponse()); + } + // Get information for multiple phone numbers + $multiplePhoneNumbers = '921234567874,921234567891'; + $multipleResponse = PhoneNumberInfo::getHlrDetails($multiplePhoneNumbers); + if ($multipleResponse->isSuccessful()) { + print_r($multipleResponse->getContent()); + } else { + print_r($multipleResponse->getErrorResponse()); + } + +### Configuration + +phone-number-info allows you to customize its behavior by publishing its configuration file. To do this, run the following artisan command: + +```bash +php artisan vendor:publish --tag="number-info-config" +``` + +After running the command, you will find the configuration file at config/phonenumberinfo.php. You can modify the settings as per your needs. + +# Available Methods + +| Method | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------------------- | +| `getNumberError($numbersErrors)` | Get the error messages related to phone numbers. | +| `getUuid($uuIds)` | Get the UUIDs associated with the phone numbers. | +| `getRequestParameters($requestParameters)` | Get the parameters used in the request for phone number information. | +| `getCreditsSpent($numberSpendCredits)` | Get the number of credits spent for retrieving phone number information. | +| `getFormattedTelephoneNumber($formattedTelephoneNumbers)` | Get the phone numbers in a formatted representation. | +| `getIsOriginalNetworkAvailable($isOriginalNetworkAvailable)` | Check if the information about the original network is available. | +| `getOriginalNetworkDetails($originalNetworkDetails)` | Get details about the original network of the phone number. | +| `getNumberType($numberTypes)` | Get the type of the phone number (e.g., mobile, landline). | +| `getIsLiveStatusAvailable($isLiveStatusAvailable)` | Check if the live status information is available. | +| `getIsCurrentNetworkAvailable($isCurrentNetworkAvailable)` | Check if the current network information is available. | +| `getCurrentNetworkDetails($currentNetworkDetails)` | Get details about the current network of the phone number. | +| `getIsNumberPorted($isNumberPorted)` | Check if the phone number is ported (i.e., transferred between carriers). | +| `getSmsEmail($smsEmail)` | Get the SMS email address associated with the phone number. | +| `getMmsEmail($mmsEmail)` | Get the MMS email address associated with the phone number. | +| | + + +## Contributions and Bug Reports +We welcome contributions from the community to improve bytes4sale phone-number-info. If you find a bug or have a suggestion for a new feature, we encourage you to participate and help make this package even better. + +### Bug Reports + +If you encounter any issues or bugs while using bytes4sale phone-number-info, please open an issue in our [GitHub repository](https://github.com/yaseenahmedpk/phone-number-info). When reporting a bug, please provide as much detail as possible, including: +- A clear and descriptive title for the issue. +- Steps to reproduce the bug. +- Information about your PHP and Laravel versions. +- Any relevant error messages or screenshots. + +### Feature Requests + +If you have a new feature idea or enhancement in mind, you can also open an issue in the [GitHub repository](https://github.com/yaseenahmedpk/phone-number-info). Please outline the feature's functionality and the problem it solves or the value it adds to the package. + +### Contributing + +We appreciate contributions from the community to help us improve the package. If you'd like to contribute code, please follow these steps: + +1. Fork the repository and create a new branch from the `master` branch. +2. Implement your changes or additions. +3. Write tests to ensure the new code functions correctly and update existing tests as needed. +4. Make sure all tests pass. +5. Create a pull request (PR) to submit your changes. Clearly describe the changes you've made and any related issues or features. + +Our team will review your PR, and if everything looks good, we'll merge it into the `master` branch. + +By contributing to bytes4sale phone-number-info, you agree to make your contributions available under this package. + +We appreciate the efforts of our contributors, and your help will make the package better for everyone. Thank you! + +## License +The MIT License (MIT). Please see [License File](https://github.com/yaseenahmedpk/phone-number-info/blob/master/LICENSE.md) for more information. + +## Acknowledgments + +If you find this package helpful, consider giving credit to the authors and contributors. + diff --git a/composer.json b/composer.json new file mode 100644 index 0000000..150fbbc --- /dev/null +++ b/composer.json @@ -0,0 +1,21 @@ +{ + "name": "bytes4sale/phone-number-info", + "description": "A Laravel package that provides comprehensive data related to phone numbers, including HLR insights, carrier details, and origin information.", + "type": "laravel-package", + "require": { + "php": "^7.3|^8.0", + "laravel/framework": "^8.75" + }, + "license": "MIT", + "autoload": { + "psr-4": { + "Bytes4sale\\PhoneNumberInfo\\": "src/" + } + }, + "authors": [ + { + "name": "Yaseen Ahmed" + } + ], + "minimum-stability": "beta" +} diff --git a/config/phoneNumberInfo.php b/config/phoneNumberInfo.php new file mode 100644 index 0000000..3a5977f --- /dev/null +++ b/config/phoneNumberInfo.php @@ -0,0 +1,18 @@ + env('API_KEY', ''), + 'api-secret' => env('API_SECRET', ''), +]; diff --git a/src/Facades/PhoneNumberInfo.php b/src/Facades/PhoneNumberInfo.php new file mode 100644 index 0000000..0e82d65 --- /dev/null +++ b/src/Facades/PhoneNumberInfo.php @@ -0,0 +1,13 @@ +getHlrDetails('923333974745'); + if ($response->isSuccessful()) { + echo "
"; + print_r($response->getCurrentNetworkDetails()); + die; + } + echo ""; + print_r($response->getContent()); + die; + } +} diff --git a/src/PhoneNumberInfoServiceProvider.php b/src/PhoneNumberInfoServiceProvider.php new file mode 100644 index 0000000..a509459 --- /dev/null +++ b/src/PhoneNumberInfoServiceProvider.php @@ -0,0 +1,34 @@ +mergeConfigFrom(__DIR__ . '/../config/phoneNumberInfo.php', 'phonenumberinfo'); + $this->app->singleton('numberinfo', function () { + return new HlrLookup(); + }); + } + + /** + * Bootstrap services. + * + * @return void + */ + public function boot() + { + $this->publishes([ + __DIR__ . '/../config/phoneNumberInfo.php' => config_path('phonenumberinfo.php'), + ], 'number-info-config'); + } +} diff --git a/src/Provider/HlrLookup.php b/src/Provider/HlrLookup.php new file mode 100644 index 0000000..41d1e2f --- /dev/null +++ b/src/Provider/HlrLookup.php @@ -0,0 +1,96 @@ +post($this->baseUrl . '/hlr', json_encode($this->prepareRequestData($number, $params)), HttpRequest::APPLICATION_JSON); + if ($response->getStatusCode() >= 200 && $response->getStatusCode() <= 300) { + $responseContentArray = json_decode($response->getContent()); + $this->prepareHlrResponse($responseContentArray->results, $response); + return $response; + } + return $response; + } + + private function prepareRequestData($numbers, $params) + { + $paramsData = []; + foreach (explode(",", $numbers) as $number) { + $paramsData[] = $this->getParams($number, $params); + } + if (config('phonenumberinfo.api-key') != null && config('phonenumberinfo.api-secret') != null) { + return [ + "api_key" => config('phonenumberinfo.api-key'), + "api_secret" => config('phonenumberinfo.api-secret'), + "requests" => $paramsData, + ]; + } else { + throw new InvalidArgumentException('Api key or Api secret is missing please set API_KEY and API_SECRET in .env file, If you have already set then please try config:cache command'); + } + } + + private function getParams($number, $params) + { + $params["telephone_number"] = $number; + return $params; + } + + private function prepareHlrResponse($responseContentArray, $response) + { + $numbersErrors = []; + $uuIds = []; + $requestParameters = []; + $numberSpendCredits = []; + $formattedTelephoneNumbers = []; + $isOriginalNetworkAvailable = []; + $originalNetworkDetails = []; + $numberTypes = []; + $isLiveStatusAvailable = []; + $isCurrentNetworkAvailable = []; + $currentNetworkDetails = []; + $isNumberPorted = []; + $smsEmail = []; + $mmsEmail = []; + foreach ($responseContentArray as $responseData) { + $numbersErrors[] = $responseData->error; + $uuIds[] = $responseData->uuid; + $requestParameters[] = $responseData->request_parameters; + $numberSpendCredits[] = $responseData->credits_spent; + $numberSpendCredits[] = $responseData->credits_spent; + $formattedTelephoneNumbers[] = $responseData->formatted_telephone_number; + $isOriginalNetworkAvailable[] = $responseData->original_network; + $originalNetworkDetails[] = $responseData->original_network_details; + $numberTypes[] = $responseData->telephone_number_type; + $isLiveStatusAvailable[] = $responseData->live_status; + $isCurrentNetworkAvailable[] = $responseData->current_network; + $currentNetworkDetails[] = $responseData->current_network_details; + $isNumberPorted[] = $responseData->is_ported; + $smsEmail[] = $responseData->sms_email; + $mmsEmail[] = $responseData->mms_email; + } + $response->setNumberError($numbersErrors); + $response->setUuid($uuIds); + $response->setRequestParameters($requestParameters); + $response->setCreditsSpent($numberSpendCredits); + $response->setFormattedTelephoneNumber($formattedTelephoneNumbers); + $response->setIsOriginalNetworkAvailable($isOriginalNetworkAvailable); + $response->setOriginalNetworkDetails($originalNetworkDetails); + $response->setNumberType($numberTypes); + $response->setIsLiveStatusAvailable($isLiveStatusAvailable); + $response->setIsCurrentNetworkAvailable($isCurrentNetworkAvailable); + $response->setCurrentNetworkDetails($currentNetworkDetails); + $response->setIsNumberPorted($isNumberPorted); + $response->setSmsEmail($smsEmail); + $response->setMmsEmail($mmsEmail); + } +} diff --git a/src/net/HttpRequest.php b/src/net/HttpRequest.php new file mode 100644 index 0000000..617baf4 --- /dev/null +++ b/src/net/HttpRequest.php @@ -0,0 +1,77 @@ +setStatusCode($statusCode); + $httpResponse->setContent($responseBody); + $httpResponse->setRequestString($url); + + if ($statusCode <= 0 || $statusCode != 200) { + $httpResponse->setSuccessful(false); + $httpResponse->setMessage("could not connect to host"); + } else { + $httpResponse->setSuccessful(true); + } + + return $httpResponse; + } + + public static function post($url, $params, $contentType, $headers = []) + { + + $headers[] = "Content-Type: $contentType"; + + $ch = curl_init(); + + curl_setopt($ch, CURLOPT_URL, $url); + curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); +// curl_setopt($ch, CURLOPT_HEADER, true); + curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); + curl_setopt($ch, CURLOPT_POST, true); + curl_setopt($ch, CURLOPT_POSTFIELDS, $params); + + $responseBody = curl_exec($ch); + $statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); + + curl_close($ch); + + $httpResponse = new HTTPResponse(); + $httpResponse->setStatusCode($statusCode); + $httpResponse->setContent($responseBody); + $httpResponse->setRequestString($url); + + if ($statusCode <= 0 || $statusCode != 200) { + $httpResponse->setSuccessful(false); + $httpResponse->setMessage("could not connect to host"); + } else { + $httpResponse->setSuccessful(true); + } + + return $httpResponse; + } +} diff --git a/src/response/HTTPResponse.php b/src/response/HTTPResponse.php new file mode 100644 index 0000000..2efb8c1 --- /dev/null +++ b/src/response/HTTPResponse.php @@ -0,0 +1,244 @@ +statusCode; + } + + /** + * @param statusCode to set status code will be used by http client to + * update the info + */ + public function setStatusCode($statusCode) + { + $this->statusCode = $statusCode; + } + + /** + * @return the content/body of http response + */ + public function getContent() + { + return $this->content; + } + + /** + * @param content to set the content/body of http response will be used by + * http client to update the info + */ + public function setContent($content) + { + $this->content = $content; + } + + public function isSuccessful() + { + return $this->successful; + } + + /** + * @param successfull the successful to set + */ + public function setSuccessful($successfull) + { + $this->successful = $successfull; + } + + /** + * @return the requestString + */ + public function getRequestString() + { + return $this->requestString; + } + + /** + * @param requestString the requestString to set + */ + public function setRequestString($requestString) + { + $this->requestString = $requestString; + } + + /** + * setMessage function + *@param string $message set response message + * @return void + */ + public function setMessage($message) + { + $this->message = $message; + } + /** + * getMessage function + * + * @return string + */ + public function getMessage() + { + return $this->message; + } + + /** + * getErrorResponse function + * + * @return array + */ + public function getErrorResponse() + { + return [ + 'successful' => $this->isSuccessful(), + 'statusCode' => $this->getStatusCode(), + 'message' => $this->getMessage(), + 'description' => $this->getContent(), + ]; + } + + public function setNumberError($numberError) + { + $this->numberError = $numberError; + } + + public function getNumberError() + { + return $this->numberError; + } + public function setUuid($uuid) + { + $this->uuid = $uuid; + } + public function getUuid() + { + return $this->uuid; + } + + public function setRequestParameters(array $requestParameters) + { + $this->requestParameters = $requestParameters; + } + public function getRequestParameters(): array + { + return $this->requestParameters; + } + public function setCreditsSpent($creditsSpent) + { + $this->creditsSpent = $creditsSpent; + } + public function getCreditsSpent() + { + return $this->creditsSpent; + } + public function setFormattedTelephoneNumber($formattedTelephoneNumber) + { + $this->formattedTelephoneNumber = $formattedTelephoneNumber; + } + public function getFormattedTelephoneNumber() + { + return $this->formattedTelephoneNumber; + } + public function setIsOriginalNetworkAvailable($isOriginalNetworkAvailable) + { + $this->isOriginalNetworkAvailable = $isOriginalNetworkAvailable; + } + public function getIsOriginalNetworkAvailable() + { + return $this->isOriginalNetworkAvailable; + } + public function setOriginalNetworkDetails(array $originalNetworkDetails) + { + $this->originalNetworkDetails = $originalNetworkDetails; + } + public function getOriginalNetworkDetails(): array + { + return $this->originalNetworkDetails; + } + public function setNumberType($numberType) + { + $this->numberType = $numberType; + } + public function getNumberType() + { + return $this->numberType; + } + public function setIsLiveStatusAvailable($isLiveStatusAvailable) + { + $this->isLiveStatusAvailable = $isLiveStatusAvailable; + } + public function getIsLiveStatusAvailable() + { + return $this->isLiveStatusAvailable; + } + public function setIsCurrentNetworkAvailable($isCurrentNetworkAvailable) + { + $this->isCurrentNetworkAvailable = $isCurrentNetworkAvailable; + } + public function getIsCurrentNetworkAvailable() + { + return $this->isCurrentNetworkAvailable; + } + public function setCurrentNetworkDetails($currentNetworkDetails) + { + $this->currentNetworkDetails = $currentNetworkDetails; + } + public function getCurrentNetworkDetails() + { + return $this->currentNetworkDetails; + } + public function setIsNumberPorted($isNumberPorted) + { + $this->isNumberPorted = $isNumberPorted; + } + public function getIsNumberPorted() + { + return $this->isNumberPorted; + } + public function setSmsEmail($smsEmail) + { + $this->smsEmail = $smsEmail; + } + public function getSmsEmail() + { + return $this->smsEmail; + } + public function setMmsEmail($mmsEmail) + { + $this->mmsEmail = $mmsEmail; + } + public function getMmsEmail() + { + return $this->mmsEmail; + } + +}