PHPackages                             ernestmarcinko/waifuvault-php-api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. ernestmarcinko/waifuvault-php-api

ActiveLibrary[File & Storage](/categories/file-storage)

ernestmarcinko/waifuvault-php-api
=================================

SDK to interact with WaifuVault, a temporary file hosting service

1.0.5(2y ago)32[1 issues](https://github.com/waifuvault/waifuVault-php-api/issues)MITPHPPHP ^8.3

Since Mar 25Pushed 2y ago1 watchersCompare

[ Source](https://github.com/waifuvault/waifuVault-php-api)[ Packagist](https://packagist.org/packages/ernestmarcinko/waifuvault-php-api)[ RSS](/packages/ernestmarcinko-waifuvault-php-api/feed)WikiDiscussions main Synced today

READMEChangelog (6)Dependencies (4)Versions (9)Used By (0)

waifuvault-php-api
==================

[](#waifuvault-php-api)

[![tests](https://github.com/waifuvault/waifuVault-php-api/actions/workflows/tests.yml/badge.svg)](https://github.com/waifuvault/waifuVault-php-api/actions/workflows/tests.yml/badge.svg)

This contains the official API bindings for uploading, deleting and obtaining files with [waifuvault.moe](https://waifuvault.moe/). Contains a full up-to-date API for interacting with the service via PHP

Installation via Composer
-------------------------

[](#installation-via-composer)

```
composer require ernestmarcinko/waifuvault-php-api
```

Usage
-----

[](#usage)

This API contains 4 interactions:

1. [Upload File](#upload-file)
2. [Get File Info](#get-file-info)
3. [Delete File](#delete-file)
4. [Get File](#get-file)
5. [Modify Entry](#modify-entry)

The only class needed is the `WaifuApi` class from `ErnestMarcinko\WaifuVault`:

```
use ErnestMarcinko\WaifuVault\WaifuApi;
```

### Upload File

[](#upload-file)

To Upload a file, use the `WaifuApi::uploadFile` function.

#### Parameters

[](#parameters)

The function accepts an **associative array** of arguments.

Param (key)TypeDescriptionRequiredExtra info`file``string`The file path to uploadtrue only if `url` or `file_contents` is not suppliedIf `url` is supplied, this prop can't be set`url``string`The URL to a file that exists on the internettrue only if `file` or `file_contents` is not suppliedIf `url` is supplied, this prop has no effect`file_contents``string`The file contentstrue only if `url` or `file` is not suppliedIf `url` or `file` is supplied, this prop can't be set`expires``string`A string containing a number and a unit (1d = 1day)falseValid units are `m`, `h` and `d``hideFilename``boolean`If true, then the uploaded filename won't appear in the URLfalseDefaults to `false``password``string`If set, then the uploaded file will be encryptedfalse`filename``string`Only used if `file_contents` or `file` is set, will set the filename of the uploadfalse`oneTimeDownload	``boolean`If true, the file is deleted after the first accessfalse#### WaifuResponse Return value

[](#waifuresponse-return-value)

The function returns a `WaifuResponse` object, throws and `Exception` or `WaifuException`. Almost all SDK functions will use this object as their return values.

```
// WaifuResponse object:

ErnestMarcinko\WaifuVault\WaifuResponse (4) {
  ["token"]=> string(36) "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx"
  ["url"]=> string(74) "https://waifuvault.moe/f/{timestamp}/{filename}.{file_ext}"
  ["retentionPeriod"]=> string(39) "334 days 20 hours 16 minutes 23 seconds",
  ["options"] ErnestMarcinko\WaifuVault\WaifuResponseOptions (4) {
	["hideFilename"]=> bool(false),
	["oneTimeDownload"]=> bool(false),
	["protected"]=> bool(false),
  }
}
```

#### Examples

[](#examples)

Using a URL:

```
use ErnestMarcinko\WaifuVault\WaifuApi;

$waifu = new WaifuApi();
$response = $waifu->uploadFile(array(
	'url' =>   'https://waifuvault.moe/assets/custom/images/08.png',
));
var_dump($response);
```

Using a file path:

```
use ErnestMarcinko\WaifuVault\WaifuApi;

$waifu = new WaifuApi();
$response = $waifu->uploadFile(array(
	'file' =>   __DIR__ . '/image.jpg',
));
var_dump($response);
```

Using a file contents:

```
use ErnestMarcinko\WaifuVault\WaifuApi;

$waifu = new WaifuApi();
$response = $waifu->uploadFile(array(
	'file_contents' => file_get_contents(__DIR__ . '/image.jpg'),
	'filename' => 'image.jpg',
));
var_dump($response);
```

### Get File Info

[](#get-file-info)

The `WaifuApi::getFileInfo` function is used to get the file information.

#### Parameters

[](#parameters-1)

ParamTypeDescriptionRequiredExtra info`token``string`The token of the uploadtrue`formatted``boolean`If you want the `retentionPeriod` to be human-readable or an epochfalsedefaults to false#### Return value

[](#return-value)

`WaifuApi::getFileInfo` returns a [WaifuResponse](#waifuresponse-object)

#### Examples

[](#examples-1)

```
use ErnestMarcinko\WaifuVault\WaifuApi;

$waifu = new WaifuApi();
$response = $waifu->getFileInfo('someToken');
var_dump($response);
```

Human-readable timestamp retention period:

```
use ErnestMarcinko\WaifuVault\WaifuApi;

$waifu = new WaifuApi();
$response = $waifu->getFileInfo('someToken');
var_dump($response->retentionPeriod); // 328 days 18 hours 51 minutes 31 seconds
```

### Delete File

[](#delete-file)

The `WaifuApi::deleteEntry` function is used to get the file information.

#### Parameters

[](#parameters-2)

ParamTypeDescriptionRequiredExtra info`token``string`The token of the file you wish to deletetrue#### Return values

[](#return-values)

> **NOTE:** `deleteFile` will only ever either return `true` or throw an exception if the token is invalid

#### Examples

[](#examples-2)

```
use ErnestMarcinko\WaifuVault\WaifuApi;

$waifu = new WaifuApi();
$response = $waifu->deleteEntry('someToken');
```

### Get File

[](#get-file)

The `WaifuApi::getFile` function is used to get the file contents from the server by supplying either the token or the unique identifier of the file (epoch/filename).

#### Parameters

[](#parameters-3)

The function accepts an **associative array** of arguments.

Param (key)TypeDescriptionRequiredExtra info`token``string`The token of the file you want to downloadtrue only if `filename` is not setif `filename` is set, then this can not be used`filename``string`The Unique identifier of the file, this is the epoch time stamp it was uploaded and the filenametrue only if `token` is not setif `token` is set, then this can not be used`password``string`The password for the file if it is protectedfalseMust be supplied if the file is uploaded with `password`> **Important!** The Unique identifier filename is the epoch/filename only if the file uploaded did not have a hidden filename, if it did, then it's just the epoch. For example: `1710111505084/08.png` is the Unique identifier for a standard upload of a file called `08.png`, if this was uploaded with hidden filename, then it would be `1710111505084.png`

#### Return value

[](#return-value-1)

The function returns the file contents.

#### Examples

[](#examples-3)

Obtain an encrypted file

```
use ErnestMarcinko\WaifuVault\WaifuApi;

$waifu = new WaifuApi();
$response = $waifu->uploadFile(array(
	'url' => 'https://waifuvault.moe/assets/custom/images/08.png',
	'password' => 'epic'
));
$contents = $waifu->getFile(array(
	'token' => $response->token,
	'password' => 'epic'
));
var_dump($contents);
```

Obtain a file from Unique identifier

```
use ErnestMarcinko\WaifuVault\WaifuApi;

$waifu = new WaifuApi();
$contents = $waifu->getFile(array(
	'filename' => '/1710111505084/08.png'
));
var_dump($contents);
```

### Modify Entry

[](#modify-entry)

The `WaifuApi::modifyEntry` is used to modify aspects of your entry such as password, removing password, decrypting the file, encrypting the file, changing the expiry, etc.

#### Parameters

[](#parameters-4)

The function accepts an **associative array** of arguments.

OptionTypeDescriptionRequiredExtra info`token``string`The token of the file you want to modifytrue`password``string`The new password or the password you want to use to encrypt the filefalse`previousPassword``string`If the file is currently protected or encrpyted and you want to change it, use this for the old passwordtrue only if `password` is set and the file is currently protectedif the file is protected already and you want to change the password, this MUST be set`customExpiry``string`a new custom expiry, see `expires` in `uploadFile`false`hideFilename``boolean`make the filename hiddenfalsefor the new URL, check the response URL prop#### Return value

[](#return-value-2)

`WaifuApi::getFileInfo` returns a [WaifuResponse](#waifuresponse-object)

#### Examples

[](#examples-4)

Set a password on a non-encrypted file:

```
use ErnestMarcinko\WaifuVault\WaifuApi;

$waifu = new WaifuApi();
$response = $waifu->modifyEntry(array(
	'token' => 'token',
	'password' => 'apple'
));
var_dump($response->protected);
```

Change a password:

```
use ErnestMarcinko\WaifuVault\WaifuApi;

$waifu = new WaifuApi();
$response = $waifu->modifyEntry(array(
	'token' => 'token',
	'password' => 'newPass'
	'previousPassword' => 'apple'
));
var_dump($response->protected);
```

change expire:

```
use ErnestMarcinko\WaifuVault\WaifuApi;

$waifu = new WaifuApi();
$response = $waifu->modifyEntry(array(
	'token' => 'token',
	'customExpiry' => "1d"
));
var_dump($response->retentionPeriod);
```

decrypt a file and remove the password:

```
use ErnestMarcinko\WaifuVault\WaifuApi;

$waifu = new WaifuApi();
$response = $waifu->modifyEntry(array(
	'token' => 'token',
	'password' => ''
	'previousPassword' => 'apple'
));
var_dump($response->protected);
```

Custom Request Handler
----------------------

[](#custom-request-handler)

The WaifuApi object can be instantiated with a custom RequestHandler (implementing RequestHandler interface). The built in request handler uses CURL.

### Default Request Handler

[](#default-request-handler)

When isntantiating the class without any parameters the default request handler is used.

```
use ErnestMarcinko\WaifuVault\WaifuApi;

$waifu = new WaifuApi();

// which is equivalent to:

$waifu = new WaifuApi( new WaifuRequestHandler() );
```

### Making your custom request handler

[](#making-your-custom-request-handler)

If you prefer your own methods to handle requests, you can create your own class and pass it on to the `WaifuApi` constructor. The class must implement the `ErnestMarcinko\WaifuVault\RequestHandler` interface.

```
use ErnestMarcinko\WaifuVault\RequestMethods;
use ErnestMarcinko\WaifuVault\RequestHandler;

class MyCustomWaifuRequestHandler implements RequestHandler {
	public function make(
		RequestMethods $method,
		string $endpoint,
		array|null $header = null,
		array|string|bool|null $post_fields = null
	): static {
		// do your thing here
		return $this;
	}

	public function getWaifu(): WaifuResponse {
		return new WaifuResponse();
	}

	public function getTrue(): true {
		return true;
	}

	public function getRaw(): string {
		return 'raw file content';
	}
}
```

Then use it via DI:

```
use ErnestMarcinko\WaifuVault\WaifuApi;

$waifu = new WaifuApi( new MyCustomWaifuRequestHandler() );
```

WaifuVault SDKs for other languages
-----------------------------------

[](#waifuvault-sdks-for-other-languages)

- [Node.js SDK](https://www.npmjs.com/package/waifuvault-node-api)
- [Python SDK](https://pypi.org/project/waifuvault/)
- [Go SDK](https://pkg.go.dev/github.com/waifuvault/waifuVault-go-api)
- [C# SDK](https://www.nuget.org/packages/Waifuvault)

###  Health Score

25

—

LowBetter than 35% of packages

Maintenance13

Infrequent updates — may be unmaintained

Popularity6

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity62

Established project with proven stability

 Bus Factor1

Top contributor holds 93.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~10 days

Total

6

Last Release

780d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/6159897?v=4)[Ernest Marcinko](/maintainers/ernestmarcinko)[@ernestmarcinko](https://github.com/ernestmarcinko)

---

Top Contributors

[![ernestmarcinko](https://avatars.githubusercontent.com/u/6159897?v=4)](https://github.com/ernestmarcinko "ernestmarcinko (27 commits)")[![VictoriqueMoe](https://avatars.githubusercontent.com/u/27996712?v=4)](https://github.com/VictoriqueMoe "VictoriqueMoe (2 commits)")

---

Tags

file storagetemporary-filesfile hostingwaifutemp file host

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/ernestmarcinko-waifuvault-php-api/health.svg)

```
[![Health](https://phpackages.com/badges/ernestmarcinko-waifuvault-php-api/health.svg)](https://phpackages.com/packages/ernestmarcinko-waifuvault-php-api)
```

###  Alternatives

[academe/laravel-azure-file-storage-driver

Azure File Storage filesystem driver for Laravel

15142.6k](/packages/academe-laravel-azure-file-storage-driver)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)