From 6bb48f5d8e20cd1fed7e34c4af76a77ad6a9997d Mon Sep 17 00:00:00 2001
From: Pierrick Le Gall <plg@piwigo.org>
Date: Thu, 4 May 2023 18:19:20 +0200
Subject: [PATCH] copy from DokuWiki

---
 pwg.images.upload.md | 158 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 158 insertions(+)
 create mode 100644 pwg.images.upload.md

diff --git a/pwg.images.upload.md b/pwg.images.upload.md
new file mode 100644
index 0000000..0e76467
--- /dev/null
+++ b/pwg.images.upload.md
@@ -0,0 +1,158 @@
+Add a photo.
+
+Similar to pwg.images.addChunk + pwg.images.add, but simpler and better
+suited for Piwigo 2.7+
+
+## Authentication
+
+This method requires authentication with an administrator user.
+
+This method requires an HTTP POST request.
+
+This method also requires a pwg_token (session valid key).
+
+## Parameters
+
+<u>**Important note**</u>: we are uploading a file, so the HTTP request
+encoding must be set to "form-data".
+
+| Key       | Example           | Mandatory?    | Description                                                                                                                                      |
+|-----------|-------------------|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
+| image     | /path/to/file.jpg | **mandatory** | the uploaded file. JPG or PNG files only.                                                                                                        |
+| category  | 123               | **mandatory** | the identifier of the destination category, use pwg.categories.getList to find existing categories                                               |
+| pwg_token | verylongstring    | **mandatory** | this is a session key, once identified you can get it with method pwg.session.getStatus                                                          |
+| chunks    | 12                | *optional*    | number of expected chunks                                                                                                                        |
+| chunk     | 0                 | *optional*    | current chunk number, from 0 to chunks-1                                                                                                         |
+| name      | A nice title      | *optional*    | the title of your photo, don't make it too long (use the comment to go into details                                                              |
+| name      | A nice title      | *optional*    | the title of your photo, don't make it too long (use the comment to go into details                                                              |
+| level     | 2                 | *optional*    | (default = 0) privacy setting. See an example in your Piwigo on screen Administration \> Photos \> Add. 0 is for everybody, 8 is for admins only |
+
+## Example
+
+Here comes a full example in Perl language (see the most updated version
+on [piwigo_upload.pl on source code
+repository](http://piwigo.org/dev/browser/trunk/tools/piwigo_upload.pl)):
+
+``` perl
+#!/usr/bin/perl
+
+####
+# Usage
+#
+# perl piwigo_upload.pl --url=http://piwigo.org/demo --user=admin --password=secret --file=photo.jpg --album_id=9
+
+use strict;
+use warnings;
+
+use JSON;
+use LWP::UserAgent;
+use Getopt::Long;
+use POSIX qw(ceil floor);
+use Digest::MD5 qw/md5 md5_hex/;
+use File::Slurp;
+use File::Basename;
+
+my %opt = ();
+GetOptions(
+    \%opt,
+    qw/
+          file=s
+          album_id=i
+          category=s
+          url=s
+          username=s
+          password=s
+      /
+);
+
+our %conf = (
+    chunk_size => 500_000,
+);
+
+our $ua = LWP::UserAgent->new;
+$ua->agent('Mozilla/piwigo_upload.pl 1.56');
+$ua->cookie_jar({});
+
+my $result = undef;
+
+my $form = {
+    method => 'pwg.session.login',
+    username => $opt{username},
+    password => $opt{password},
+};
+
+$result = $ua->post(
+    $opt{url}.'/ws.php?format=json',
+    $form
+);
+
+my $response = $ua->post(
+    $opt{url}.'/ws.php?format=json',
+    {
+        method => 'pwg.session.getStatus',
+    }
+);
+
+my $pwg_token = from_json($response->content)->{result}->{pwg_token};
+
+my $content = read_file($opt{file});
+my $content_length = length($content);
+my $nb_chunks = ceil($content_length / $conf{chunk_size});
+
+my $chunk_pos = 0;
+my $chunk_id = 0;
+
+while ($chunk_pos < $content_length) {
+    my $chunk = substr(
+        $content,
+        $chunk_pos,
+        $conf{chunk_size}
+    );
+
+    # write the chunk as a temporary local file
+    my $chunk_path = '/tmp/'.md5_hex($opt{file}).'.chunk';
+
+    open(my $ofh, '>'.$chunk_path) or die "problem for writing temporary local chunk";
+    print {$ofh} $chunk;
+    close($ofh);
+
+    $chunk_pos += $conf{chunk_size};
+
+    my $response = $ua->post(
+        $opt{url}.'/ws.php?format=json',
+        {
+            method => 'pwg.images.upload',
+            chunk => $chunk_id,
+            chunks => $nb_chunks,
+            category => $opt{album_id},
+            pwg_token => $pwg_token,
+            file => [$chunk_path],
+            name => basename($opt{file}),
+        },
+        'Content_Type' => 'form-data',
+    );
+
+    unlink($chunk_path);
+
+    printf(
+        'chunk %03u of %03u for "%s"'."\n",
+        $chunk_id+1,
+        $nb_chunks,
+        $opt{file}
+    );
+
+    if ($response->code != 200) {
+        printf("response code    : %u\n", $response->code);
+        printf("response message : %s\n", $response->message);
+    }
+
+    $chunk_id++;
+}
+
+$result = $ua->get(
+    $opt{url}.'/ws.php?format=json',
+    {
+        method => 'pwg.session.logout'
+    }
+);
+```