# GestorArchivos (MinIO)

Servicio para manejar archivos en MinIO y local en API's Sisoft.




## 🏗️ Deployment

Para que funcione bien el servicio debe asegurarse de tener configurado las variables de entorno y los discos correctamente.

#### Variables de entorno
Estas son variables que se utilizarán en los discos para retornar la url del archivo con el alias de apache cuando se estén utilizando rutas de docsAPP/...

Aquí deben configurarsen las URL de las aplicaciones

`APP_URL_FINANZAS`
`APP_URL_CONTRACTVS`
`APP_URL_CONTRATISTA`
`APP_URL_SIGD`

En `config/filesystems.php` deben estar los siguientes discos configurados:
```php
'ctvMinio' => [
    'driver' => 'local',
    'root' => base_path('../docsAPP'),
    'url' => env('APP_URL_CONTRACTVS'),
],
'contratistaMinio' => [
    'driver' => 'local',
    'root' => base_path('../docsAPP'),
    'url' => env('APP_URL_CONTRATISTA'),
],
'finanzasMinio' => [
    'driver' => 'local',
    'root' => base_path('../docsAPP'),
    'url' => env('APP_URL_FINANZAS'),
],
'sigdMinio' => [
    'driver' => 'local',
    'root' => base_path('../docsAPP'),
    'url' => env('APP_URL_SIGD'),
],
```



## ℹ️ API Reference

#### Obtener bucket configurado
`string` Retorna nombre de bucket
```bash
  getMinioBucket()
```

#### getter estado minIO
`bool` Retorna el estado de minIO en la aplicación.
```bash
  getS3MinioStatus()
```


#### Getter/setter alias apache de docsAPP
-Normalmente una Url de algún documento usando docsAPP se entrega ../finanzas/documents/ruta/al/archivo. Pero en ocasiones ese alias cambia según la empresa.

 `String`  Retorna el nombre del alias. **Por defecto es documents**
```bash
  getAliasDocs()
```
Cambiar el alias que está por defecto (documents)
```bash
  setAliasDocs($aliasDocs)
```
| Parameter | Type     | Description                       |
| :-------- | :------- | :-------------------------------- |
| `$aliasDocs`      | `string` | **Required**. Nombre alias. |


#### Getter/setter folder minIO
-Esta carpeta se usa para referenciar el destino en minIO.

 `String`  Retorna el nombre de la carpeta de minio que se haya parametrizado en el objeto.
```bash
  getFolderMinio()
```
Cambiar la carpeta FolderMinio.
```bash
  setFolderMinio($folderMinio)
```
| Parameter | Type     | Description                       |
| :-------- | :------- | :-------------------------------- |
| `$folderMinio`      | `string` | **Required**. Nombre de la carpeta. |

#### Getter/setter disco local
-Este disco se usa para gestionar archivos cuando el minio esté desactivado. El disco debe estar previamente configurado en config/filesystems.php

 `String`  Retorna el nombre del disco prarametrizado en el objeto. 
```bash
  getLocalDisk()
```
Cambiar disco local
```bash
  setLocalDisk($localDisk)
```
| Parameter | Type     | Description                       |
| :-------- | :------- | :-------------------------------- |
| `$localDisk`      | `string` | **Required**. Nombre del disco (debe existir en filesystems.php)|

#### 📦️Guardar un archivo
Guarda un archivo en local o minio dependiendo de su estado activo.
```bash
  saveFile(string|UploadedFile $file, string $path, array  $options)
```
| Parameter | Type     | Description |
| :-------- | :------- | :---------- |
| `$file`   | `string`,`UploadedFile`| **Required**. ruta o archivo a guardar)|
|`$path` | `string` | **Optional**. Ruta Destino. **Requerido** si se sube un archivo que viene de un formulario|
|`$options` | `array` | **Optional**. opciones de guardado. (Aplica estos efectos: newName, delete, ignoreExists, storage) |

- el parámetro `$options` se envía como array. ej: ['delete' =>true] en la siguiente tabla se muestran sus efectos

| Option | Type     | Default | Description |
| :-------- | :------- | :---------- | :---------- |
| `newName`   | `boolean`| `true`|**true**. Crea un nuevo nombre del archivo usando el método `Uuid::uuid4()->toString()`|
|   | | |**false**. Mantiene el nombre original. Si en la carpeta destino ya existe un archivo con el mismo nombre, entonces la opción `ignoreExists` se encargará|
| `delete`   | `boolean`| `false`|**true**. Elimina el archivo cuando se sube un archivo desde local|
| | | |**false**. Sin efectos|
| `ignoreExists`   | `boolean`| `false`|**true**. Reemplaza el archivo en la carpeta destino por el entrante|
| | | |**false**. Sin efectos. Mantiene el archivo existente e ignora el entrante|
| `storage`   | `boolean`| `false`|**true**. Para su uso con rutas en el storage|
| | | |**false**. Para su uso con rutas en docsAPP|

`Array` Datos de retorno

| Return Data | Type     | Description |
| :-------- | :------- | :---------- |
| `path`   | `string`|ruta relativa|
|`url` | `string` | ruta absoluta|
|`name` | `string` | nombre del archivo |
|`publicUrl` | `string` | url pública|

#### 👁️‍🗨️️ Obtener un archivo
El método **getFile() está depreciado**, en su lugar usa **showFile()**

Devuelve la ruta del archivo para mostrar. No confundir con `downloadFile()`

❌️`getFile(string $path, string $disk, string $folderMinio)`

| Parameter | Type     | Description |
| :-------- | :------- | :---------- |
| `$path`   | `string`| **Required**. ruta del archivo a obtener|
|`$disk` | `string` | **Required**. Nombre del disco|
|`$folderMinio` | `string` | **Optional**. Carpeta destino de minio|

`Array` Datos de retorno

| Return Data | Type     | Description |
| :-------- | :------- | :---------- |
|`from` | `bool` | `true` si viene de minio |
|`exists` | `bool` | `true` si existe el archivo |
|`url` | `string` | ruta del archivo |

Devuelve la ruta del archivo para mostrar. No confundir con `downloadFile()`

✅️`showFile(string $path, array $options)`

| Parameter | Type     | Description |
| :-------- | :------- | :---------- |
| `$path`   | `string`| **Required**. ruta del archivo a obtener|
|`$options` | `array` | **Optional**. Nombre del disco (aplica efectos de storage)|


`Array` Datos de retorno


| Return Data | Type     | Description |
| :-------- | :------- | :---------- |
| `fromCloud`   | `bool`| si viene de minio o local|
|`exists` | `bool` | si el archivo existe en minio o local|
|`path` | `string` | ruta de entrada|
|`url` | `string` | ruta absoluta|
|`publicUrl` | `string` | url pública (útil para mostrar al usuario)|

### 📥️ Descargar/mover un archivo a local

- Este método permite mover o descargar un archivo de minio a local, cuando el almacenamiento en la nube está activado.
- La ruta de origen debe ser la misma de destino. Es decir, si la ruta en minIO es `documents/archivos/archivo` en local ela rchivo se guardará en `documents/archivos/archivo`

- Cuando Minio está desactivado retornará el archivo mismo que está en local.

`downloadFile(string $path, array $options)`


| Parameter | Type     | Description |
| :-------- | :------- | :---------- |
| `$path`   | `string`| **Required**. ruta del archivo a descargar|
|`$options` | `array` | **Optional**. Opciones (aplica estos efectos: storage, ignoreExists, delete)|

`array` Datos de retorno

| Return Data | Type     | Description |
| :-------- | :------- | :---------- |
| `local`   | `bool`| si viene de minio o local|
|`exists` | `bool` | si el archivo existe en minio o local|
|`path` | `string` | ruta de entrada|
|`url` | `string` | ruta absoluta|

### ❎️ Eliminar un archivo

elimina uno o varios archivos si existen

`deleteFile(string|array $path, array $options)`

| Parameter | Type     | Description |
| :-------- | :------- | :---------- |
| `$path`   | `string` `array` | **Required**. ruta del archivo. Se pueden enviar varias rutas en un array unidimensional|
|`$options` | `array` | **Optional**. Opciones (aplica estos efectos: storage)|

`void` Datos de retorno

### 📗️📗️ Copiar/Mover un archivo

Este método permite copiar un archivo de una carpeta a otra

`copyFile(string $source, string $destination, string $folder2, $options)`

| Parameter | Type     | Description |
| :-------- | :------- | :---------- |
| `$source`   | `string` `array` | **Required**. ruta de origen|
| `$destination`   | `string` `array` | **Required**. ruta de destino|
| `$folder2`   | `string` `array` | **NO USAR**.  carpeta padre destino en minio (En desarrollo)|
|`$options` | `array` | **Optional**. Opciones (aplica estos efectos: storage, ignoreExists, delete)|
`array` Datos de retorno

| Return Data | Type     | Description |
| :-------- | :------- | :---------- |
| `cloudExists`   | `bool`| si existe en cloud|
|`localExists` | `bool` | si existe en local|
|`destination` | `string` | ruta destino|
|`publicUrl` | `string` | ruta pública|
## Preguntas Frecuentes

#### ¿Para mostrar un archivo puedo usar el método `downloadFile()`?

Para mostrar un archivo al usuario final se debe usar `showFile()` esto entregará la url (publicUrl) que sirve para mostrar el archivo. Dependiendo de la configuración la url vendrá de minio, storage o docsAPP (usando alias apache).

#### ¿Existe un método para saber si un archivo existe?

Cuando se quiera saber si un archivo existe se puede utilizar el método `showFile()` pues este entre sus datos de respuesta entrega `fromCloud` y `exists` el primero devolverá `true`/`false` si el archivo viene de cloud y el segundo devolverá `true`/`false` si el archivo existe en cloud o en local. Así que si `exists = true` significa entonces que el archivo existe en alguno de los lugares y si además `fromCloud = true` entonces existe en cloud.

#### ¿En que casos podría usar el método `downloadFile()`?

Este método es bastante útil en las plantillas.

Si la plantilla llegase a estar en cloud debería descargarse primero a local para poder ser utilizada entonces este método trae el archivo y lo deja en la misma ruta que tiene en cloud.

El siguiente es un código de ejemplo de uso:

```PHP
$templateExists = $this->gestorArchivos->showFile($template, ['storage' => true]);
            if (!$templateExists['exists']) {
                throw new Exception('La plantilla No se encuentra en servidor. Comunícate con soporte', 1);
            } else if ($templateExists['fromCloud']) {
                $this->gestorArchivos->downloadFile($template, ['storage' => true]);
            }
```

- En la primer línea usa el método `showFile()` para saber si existe el archivo.
- En la segunda línea verifica si el archivo existe independientemente de si está en cloud o local. De no existir retornará el mensaje *'La plantilla No se encuentra en servidor. Comunícate con soporte'*
- En la cuarta línea ya se sabe que si existe pero ahora comprueba en dónde existe ya que si está en cloud entonces debe ser descargado con `downloadFile()`

Con lo anterior se asegura que el archivo siempre esté presente en local y no genere problemas (para este caso) al momento de generar archivos con la plantilla.