# Installing an SDK > Install TXTextControl.ReportingCloud from NuGet, the PHP SDK with Composer, the Java library from source or the Ruby gem, and check it with a first call. - **Product:** ReportingCloud - **Section:** Documentation - **Kind:** Topic - **Path:** ReportingCloud > Installation Guide > Installing an SDK - **3508 words** - **Web URL:** https://docs.textcontrol.com/reporting-cloud/installation/sdks/ - **LLMs URL:** https://docs.textcontrol.com/reporting-cloud/installation/sdks/llms.txt - **LLMs-Full URL:** https://docs.textcontrol.com/reporting-cloud/installation/sdks/llms-full.txt --- Text Control publishes SDKs for .NET, PHP, Java and Ruby that send the requests of the ReportingCloud Web API for you: you create a `ReportingCloud` object with your credentials and call its methods instead of building HTTP requests and JSON. The .NET SDK comes from nuget.org, the PHP SDK from Packagist and the Ruby SDK from RubyGems; the Java SDK is built from its source code. Each section below installs one SDK and checks the installation with a first request to your account. An SDK is optional. Any HTTP client can call the Web API, as the [Web API](https://docs.textcontrol.com/reporting-cloud/getting-started/web-api/llms-full.txt) tutorial does with curl. [Requirements](https://docs.textcontrol.com/reporting-cloud/installation/requirements/#sdk-requirements) lists the runtime each SDK needs, and [SDKs](https://docs.textcontrol.com/reporting-cloud/sdks/llms-full.txt) compares what they offer. ### .NET The package `TXTextControl.ReportingCloud` contains builds for .NET Framework 4.5 or later, .NET Core and .NET 5 or later, and .NET Standard 1.3. Its classes are in the namespace `TXTextControl.ReportingCloud`. #### Install the Package - **.NET CLI:** run the following command in the folder of your project: ```bash dotnet add package TXTextControl.ReportingCloud ``` - **Visual Studio:** choose **Manage NuGet Packages...** from the **Project** menu, select **nuget.org** as the **Package source**, search for `TXTextControl.ReportingCloud` and install it. In the **Package Manager Console**, the command is: ```powershell Install-Package TXTextControl.ReportingCloud ``` Up to November 2018, the .NET Core version of the SDK was the separate package `TXTextControl.ReportingCloud.Core`, and `TXTextControl.ReportingCloud` contained the .NET Framework build only. Since version 1.200.500, `TXTextControl.ReportingCloud` contains all three builds, and `TXTextControl.ReportingCloud.Core` is no longer updated. Use `TXTextControl.ReportingCloud` for new projects. #### Check the Installation Create a console application, add the package and run a first request: ```bash dotnet new console -o ReportingCloudCheck cd ReportingCloudCheck dotnet add package TXTextControl.ReportingCloud ``` Replace the content of *Program.cs* with the following code: ```csharp using TXTextControl.ReportingCloud; // Read the API key from an environment variable string apiKey = Environment.GetEnvironmentVariable("REPORTINGCLOUD_API_KEY") ?? throw new InvalidOperationException("Set REPORTINGCLOUD_API_KEY first."); ReportingCloud rc = new ReportingCloud(apiKey); AccountSettings settings = rc.GetAccountSettings(); Console.WriteLine($"Plan: {settings.SerialNumber}"); Console.WriteLine($"Documents this month: {settings.CreatedDocuments} of {settings.MaxDocuments}"); ``` The code works as follows: - `new ReportingCloud(apiKey)` creates the client with an API key. It sends every request to `https://api.reporting.cloud` with the header `Authorization: ReportingCloud-APIKey `. - `GetAccountSettings` calls `GET /v1/account/settings` and returns an `AccountSettings` object. `SerialNumber` is `Trial` for a trial account and the serial number of the subscription for a paid account. - A request that fails throws an `ArgumentException` with the message of the Web API. Set `REPORTINGCLOUD_API_KEY` to one of your [API keys](https://docs.textcontrol.com/reporting-cloud/installation/api-keys/llms-full.txt) and start the application with `dotnet run`. It prints the plan and the documents created this month. #### Vulnerability Warnings The package was last published in September 2019, and its dependencies are as old. In a .NET 10 project, `dotnet add package` and `dotnet build` report `NU1903` warnings ("has a known high severity vulnerability") for three of them: | Package | Required by | |---|---| | `Newtonsoft.Json` 10.0.3 | Every build of the SDK | | `Microsoft.NETCore.App` 1.1.2 | The `netcoreapp1.1` build that .NET Core and .NET 5 or later use | | `Microsoft.NETCore.Jit` 1.1.2 | `Microsoft.NETCore.App` 1.1.2 | A direct reference to a current version of `Newtonsoft.Json` replaces version 10.0.3 in your project and removes its warning: ```bash dotnet add package Newtonsoft.Json ``` With `Newtonsoft.Json` 13.0.4 in the project, the SDK sends its requests and reads the JSON responses as before. The warnings for `Microsoft.NETCore.App` and `Microsoft.NETCore.Jit` remain, because the `netcoreapp1.1` build of the package depends on them. If they are not acceptable in your project, call the Web API with `HttpClient` instead of the SDK. ### PHP The Composer package `textcontrol/textcontrol-reportingcloud` installs the PHP SDK and its dependencies, among them the HTTP client Guzzle 7. Its classes are in the namespace `TextControl\ReportingCloud`. #### Install the Package Run [Composer](https://getcomposer.org/) in the folder of your project: ```bash composer require textcontrol/textcontrol-reportingcloud:^4.0 ``` On PHP 8.3 and later, Composer installs version 4.0.5. On PHP 8.1 and 8.2, it installs 4.0.2, the newest release that supports them. Then load the Composer autoloader in your scripts: ```php require_once __DIR__ . '/vendor/autoload.php'; ``` Older projects may require the SDK by its earlier name, `textcontrol/txtextcontrol-reportingcloud`, which Packagist marks as abandoned; [Requirements](https://docs.textcontrol.com/reporting-cloud/installation/requirements/#php) lists its releases. The current package, `textcontrol/textcontrol-reportingcloud` 4.0.0 of September 2023, also moved the classes from the namespace `TxTextControl\ReportingCloud` to `TextControl\ReportingCloud`, so code written for an earlier version needs its `use` statements changed. #### Check the Installation Save the following script as *check.php* in the folder of your project: ```php (string) getenv('REPORTINGCLOUD_API_KEY'), ]); $settings = $reportingCloud->getAccountSettings(); printf("Plan: %s\n", $settings['serial_number']); printf("Documents this month: %d of %d\n", $settings['created_documents'], $settings['max_documents']); ``` The code works as follows: - The `'api_key'` option passes the API key to the constructor. `getenv` returns `false` when the variable is not set, and the cast turns it into a string, which the `setApiKey` method behind the option expects. - `getAccountSettings` calls `GET /v1/account/settings` and returns an array with keys such as `serial_number`, `created_documents` and `max_documents`. Run it with `php check.php` after setting `REPORTINGCLOUD_API_KEY` to one of your [API keys](https://docs.textcontrol.com/reporting-cloud/installation/api-keys/llms-full.txt). The *demo* folder of the package, *vendor/textcontrol/textcontrol-reportingcloud/demo*, contains sample scripts for most tasks of the Web API, such as *merge-document-basic.php* and *manage-api-keys.php*. They read the API key from `REPORTING_CLOUD_API_KEY`, not from `REPORTINGCLOUD_API_KEY`. [PHP](https://docs.textcontrol.com/reporting-cloud/sdks/php/#demo-scripts) describes the demo scripts. > Warning > > **The API Key Demo Deletes Keys.** *manage-api-keys.php* deletes every API key of the account except the one it runs with. ### Java The Java SDK is not available from Maven Central. You build it from its repository with the Gradle wrapper and add the result to your project. #### Build the Library The build needs the Java JDK 8, as the README of the repository states. Clone the repository and run the build: ```bash git clone https://github.com/TextControl/txtextcontrol-reportingcloud-java.git cd txtextcontrol-reportingcloud-java bash gradlew build -x test ``` The script *gradlew* is not marked as executable in the repository, so the command starts it with `bash`; `sh` fails on Linux distributions whose `sh` is `dash`, such as Debian and Ubuntu. The wrapper runs only on JDK 8: on a current JDK, Gradle 2.9 stops with `Could not determine java version`, and [Java](https://docs.textcontrol.com/reporting-cloud/getting-started/java/llms-full.txt) in Getting Started builds the SDK with `javac` instead. On Windows, run `gradlew.bat build -x test`. The wrapper downloads Gradle 2.9 on the first run. `-x test` leaves out the unit tests of the repository, which call the Web API with the credentials of a test account and don't find their credentials file on Linux and macOS; [Java](https://docs.textcontrol.com/reporting-cloud/sdks/java/#build-the-sdk) explains them. Add the JAR file of the library to your project, together with its dependencies: Gson 1.7.2 (`com.google.code.gson:gson:1.7.2`) and, for the class `FindAndReplaceBody`, JavaFX (`javafx.util.Pair`), which a JDK with JavaFX or the library `org.openjfx:javafx-base` provides. `bash gradlew javadoc` creates the API documentation of the library. #### Check the Installation The Java SDK authenticates with the user name (the email address you signed up with) and password of the account; it has no constructor for an API key: ```java import com.textcontrol.reportingcloud.ReportingCloud; import java.io.IOException; public class CheckInstallation { public static void main(String[] args) throws IOException { // The user name is the email address of the account ReportingCloud reportingCloud = new ReportingCloud( System.getenv("REPORTINGCLOUD_USERNAME"), System.getenv("REPORTINGCLOUD_PASSWORD")); int count = reportingCloud.getTemplateCount(); System.out.println("Templates in storage: " + count); } } ``` `getTemplateCount` calls `GET /v1/templates/count` and returns the number of templates in your template storage. The check doesn't read the account settings as the other SDKs do: on a trial account, whose subscription end date `validUntil` is `null`, `getAccountSettings` of SDK 1.3 throws a `JsonParseException`. See [GET /v1/account/settings](https://docs.textcontrol.com/reporting-cloud/reference/web-api/account/settings/get/llms-full.txt). ### Ruby The gem `txtextcontrol-reportingcloud` installs the Ruby SDK. It has no runtime dependencies. #### Install the Gem Install it with RubyGems: ```bash gem install txtextcontrol-reportingcloud ``` In an application that uses Bundler, add the gem to the *Gemfile* instead: ```ruby gem 'txtextcontrol-reportingcloud' ``` Then run `bundle install`. On Ruby 4.0, also add `gem 'base64'` and `gem 'ostruct'`: the gem loads `ostruct`, Ruby code that decodes its documents loads `base64`, and Ruby 4.0 no longer provides either to Bundler by default. #### Check the Installation Like the Java SDK, the Ruby SDK authenticates with the user name and password of the account: ```ruby require "txtextcontrol/reportingcloud" # The user name is the email address of the account reporting_cloud = TXTextControl::ReportingCloud::ReportingCloud.new( ENV["REPORTINGCLOUD_USERNAME"], ENV["REPORTINGCLOUD_PASSWORD"]) settings = reporting_cloud.get_account_settings puts "Plan: #{settings.serial_number}" puts "Documents this month: #{settings.created_documents} of #{settings.max_documents}" ``` `get_account_settings` calls `GET /v1/account/settings` and returns an `AccountSettings` object. For a trial account, `serial_number` is the symbol `:trial`. ### Next Steps - [.NET](https://docs.textcontrol.com/reporting-cloud/sdks/dotnet/llms-full.txt): the methods of the .NET SDK, with a merge example. - [PHP](https://docs.textcontrol.com/reporting-cloud/sdks/php/llms-full.txt): the methods of the PHP SDK, with a merge example. - [Java](https://docs.textcontrol.com/reporting-cloud/sdks/java/llms-full.txt): the methods of the Java SDK, with a merge example. - [Ruby](https://docs.textcontrol.com/reporting-cloud/sdks/ruby/llms-full.txt): the methods of the Ruby SDK, with a merge example. - [ASP.NET Core](https://docs.textcontrol.com/reporting-cloud/getting-started/dotnet/aspnet-core/llms-full.txt): merge a template into a PDF with the .NET SDK. - [PHP](https://docs.textcontrol.com/reporting-cloud/getting-started/php/llms-full.txt): merge a template into a PDF with the PHP SDK. - [Java](https://docs.textcontrol.com/reporting-cloud/getting-started/java/llms-full.txt): build the Java SDK and merge a template into a PDF. - [Ruby](https://docs.textcontrol.com/reporting-cloud/getting-started/ruby/llms-full.txt): merge a template into a PDF with the Ruby SDK. - [Authentication](https://docs.textcontrol.com/reporting-cloud/document-processing/authentication/llms-full.txt): how each SDK sends your credentials. --- ## Nearby - **Previous:** [API Keys](https://docs.textcontrol.com/reporting-cloud/installation/api-keys/llms-full.txt) - **Next:** [Upgrading to a Subscription](https://docs.textcontrol.com/reporting-cloud/installation/subscription/llms-full.txt)