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;
+    }
+
+}